refactor(topology): introduce TopologyRepository protocol with DTO return types

Replace repo: BaseRepository with a structural TopologyRepository protocol
in persistence.py and allocator.py. All read methods now return typed DTOs
(TopologySummary, LANRow, DeckyRow, EdgeRow) instead of raw dicts, eliminating
silent field-shape regressions across the topology subsystem.

TopologySummary gains email_personas and language_default so api_personas.py
can continue reading those fields via attribute access. hydrate() converts
DTOs to dicts before passing to _backfill_decky_configs, keeping the mutable
working-state function dict-based at its boundary. All production callers
(router handlers, mutator, CLI, heartbeat) migrated from dict/get access to
attribute access. 134 tests pass.

decnet/topology/allocator.py

@@ -14,8 +14,8 @@ from __future__ import annotations
 from ipaddress import IPv4Network
 from typing import Iterable
 
+from decnet.topology.repository import TopologyRepository
 from decnet.topology.status import TopologyStatus
-from decnet.web.db.repository import BaseRepository
 
 
 class AllocatorExhausted(RuntimeError):
@@ -150,13 +150,12 @@ _SUBNET_CLAIMING_STATES: frozenset[str] = frozenset(
 )
 
 
-async def reserved_subnets(repo: BaseRepository) -> set[str]:
+async def reserved_subnets(repo: TopologyRepository) -> set[str]:
     """All LAN subnets currently claimed by non-torn-down topologies."""
     out: set[str] = set()
     for status in _SUBNET_CLAIMING_STATES:
         for topo in await repo.list_topologies(status=status):
-            for lan in await repo.list_lans_for_topology(topo["id"]):
-                subnet = lan.get("subnet")
-                if subnet:
-                    out.add(subnet)
+            for lan in await repo.list_lans_for_topology(topo.id):
+                if lan.subnet:
+                    out.add(lan.subnet)
     return out

decnet/topology/persistence.py

@@ -5,13 +5,13 @@ from ipaddress import IPv4Address, IPv4Network
 from typing import Any
 
 from decnet.topology.allocator import IPAllocator
-from decnet.web.db.repository import BaseRepository
+from decnet.topology.repository import TopologyRepository
 from decnet.topology.config import GeneratedTopology
 from decnet.topology.status import TopologyStatus, assert_transition
 
 
 async def persist(
-    repo: BaseRepository,
+    repo: TopologyRepository,
     plan: GeneratedTopology,
     *,
     target_host_uuid: str | None = None,
@@ -91,7 +91,7 @@ async def persist(
 
 
 async def transition_status(
-    repo: BaseRepository,
+    repo: TopologyRepository,
     topology_id: str,
     new_status: str,
     reason: str | None = None,
@@ -104,11 +104,11 @@ async def transition_status(
     topo = await repo.get_topology(topology_id)
     if topo is None:
         raise ValueError(f"topology {topology_id!r} not found")
-    assert_transition(topo["status"], new_status)
+    assert_transition(topo.status, new_status)
     await repo.update_topology_status(topology_id, new_status, reason=reason)
 
 
-async def hydrate(repo: BaseRepository, topology_id: str) -> dict[str, Any] | None:
+async def hydrate(repo: TopologyRepository, topology_id: str) -> dict[str, Any] | None:
     """Load a topology + children into a single dict for callers.
 
     Shape::
@@ -125,15 +125,21 @@ async def hydrate(repo: BaseRepository, topology_id: str) -> dict[str, Any] | No
     topo = await repo.get_topology(topology_id)
     if topo is None:
         return None
-    lans = await repo.list_lans_for_topology(topology_id)
-    deckies = await repo.list_topology_deckies(topology_id)
-    edges = await repo.list_topology_edges(topology_id)
-    _backfill_decky_configs(lans, deckies, edges)
+    lans_dto = await repo.list_lans_for_topology(topology_id)
+    deckies_dto = await repo.list_topology_deckies(topology_id)
+    edges_dto = await repo.list_topology_edges(topology_id)
+    # Convert to dicts for _backfill_decky_configs (mutates decky_config in-place).
+    # mode="json" is mandatory: datetime fields must arrive as ISO strings for all
+    # downstream consumers (canonical_hash, deployer, api_get_topology, etc.).
+    lan_dicts = [m.model_dump(mode="json") for m in lans_dto]
+    decky_dicts = [m.model_dump(mode="json") for m in deckies_dto]
+    edge_dicts = [m.model_dump(mode="json") for m in edges_dto]
+    _backfill_decky_configs(lan_dicts, decky_dicts, edge_dicts)
     return {
-        "topology": topo,
-        "lans": lans,
-        "deckies": deckies,
-        "edges": edges,
+        "topology": topo.model_dump(mode="json"),
+        "lans": lan_dicts,
+        "deckies": decky_dicts,
+        "edges": edge_dicts,
     }
 
 

decnet/topology/repository.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Protocol
+
+from decnet.web.db.models.topology import DeckyRow, EdgeRow, LANRow, TopologySummary
+
+
+class TopologyRepository(Protocol):
+    """Structural contract for the topology subsystem's repo dependency.
+
+    Declares only the 10 methods the topology package actually calls.
+    Any object with matching async signatures satisfies this Protocol
+    without inheritance — including BaseRepository and test stubs.
+    """
+
+    async def create_topology(self, data: dict[str, Any]) -> str: ...
+    async def get_topology(self, topology_id: str) -> Optional[TopologySummary]: ...
+    async def update_topology_status(
+        self, topology_id: str, new_status: str, reason: Optional[str] = None
+    ) -> None: ...
+    async def list_topologies(
+        self, status: Optional[str] = None
+    ) -> list[TopologySummary]: ...
+    async def add_lan(self, data: dict[str, Any]) -> str: ...
+    async def list_lans_for_topology(self, topology_id: str) -> list[LANRow]: ...
+    async def add_topology_decky(self, data: dict[str, Any]) -> str: ...
+    async def list_topology_deckies(self, topology_id: str) -> list[DeckyRow]: ...
+    async def add_topology_edge(self, data: dict[str, Any]) -> str: ...
+    async def list_topology_edges(self, topology_id: str) -> list[EdgeRow]: ...