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/web/db/models/topology.py

@@ -237,6 +237,8 @@ class TopologySummary(BaseModel):
     needs_resync: bool = False
     created_at: datetime
     status_changed_at: Optional[datetime] = None
+    email_personas: str = "[]"
+    language_default: str = "en"
 
 
 class TopologyListResponse(BaseModel):

decnet/web/db/repository.py

@@ -1,6 +1,8 @@
 from abc import ABC, abstractmethod
 from typing import Any, Optional
 
+from decnet.web.db.models.topology import DeckyRow, EdgeRow, LANRow, TopologySummary
+
 
 class BaseRepository(ABC):
     """Abstract base class for DECNET web dashboard data storage."""
@@ -699,7 +701,7 @@ class BaseRepository(ABC):
     async def create_topology(self, data: dict[str, Any]) -> str:
         raise NotImplementedError
 
-    async def get_topology(self, topology_id: str) -> Optional[dict[str, Any]]:
+    async def get_topology(self, topology_id: str) -> Optional[TopologySummary]:
         raise NotImplementedError
 
     async def list_topologies(
@@ -707,7 +709,7 @@ class BaseRepository(ABC):
         status: Optional[str] = None,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
-    ) -> list[dict[str, Any]]:
+    ) -> list[TopologySummary]:
         raise NotImplementedError
 
     async def count_topologies(self, status: Optional[str] = None) -> int:
@@ -732,7 +734,7 @@ class BaseRepository(ABC):
     ) -> bool:
         raise NotImplementedError
 
-    async def list_topologies_needing_resync(self) -> list[dict[str, Any]]:
+    async def list_topologies_needing_resync(self) -> list[TopologySummary]:
         raise NotImplementedError
 
     async def add_lan(self, data: dict[str, Any]) -> str:
@@ -750,7 +752,7 @@ class BaseRepository(ABC):
 
     async def list_lans_for_topology(
         self, topology_id: str
-    ) -> list[dict[str, Any]]:
+    ) -> list[LANRow]:
         raise NotImplementedError
 
     async def add_topology_decky(self, data: dict[str, Any]) -> str:
@@ -768,7 +770,7 @@ class BaseRepository(ABC):
 
     async def list_topology_deckies(
         self, topology_id: str
-    ) -> list[dict[str, Any]]:
+    ) -> list[DeckyRow]:
         raise NotImplementedError
 
     async def add_topology_edge(self, data: dict[str, Any]) -> str:
@@ -776,7 +778,7 @@ class BaseRepository(ABC):
 
     async def list_topology_edges(
         self, topology_id: str
-    ) -> list[dict[str, Any]]:
+    ) -> list[EdgeRow]:
         raise NotImplementedError
 
     async def list_topology_status_events(

decnet/web/db/sqlmodel_repo/topology/_core.py

@@ -8,10 +8,8 @@ from typing import Any, Optional
 from sqlalchemy import desc, func, select, text
 
 from decnet.web.db.models import Topology, TopologyStatusEvent
-from decnet.web.db.sqlmodel_repo._helpers import (
-    _deserialize_json_fields,
-    _serialize_json_fields,
-)
+from decnet.web.db.models.topology import TopologySummary
+from decnet.web.db.sqlmodel_repo._helpers import _serialize_json_fields
 
 
 class TopologyCoreMixin:
@@ -32,7 +30,7 @@ class TopologyCoreMixin:
             await session.refresh(row)
             return row.id
 
-    async def get_topology(self, topology_id: str) -> Optional[dict[str, Any]]:
+    async def get_topology(self, topology_id: str) -> Optional[TopologySummary]:
         async with self._session() as session:
             result = await session.execute(
                 select(Topology).where(Topology.id == topology_id)
@@ -40,15 +38,14 @@ class TopologyCoreMixin:
             row = result.scalar_one_or_none()
             if not row:
                 return None
-            d = row.model_dump(mode="json")
-            return _deserialize_json_fields(d, ("config_snapshot",))
+            return TopologySummary.model_validate(row.model_dump(mode="json"))
 
     async def list_topologies(
         self,
         status: Optional[str] = None,
         limit: Optional[int] = None,
         offset: Optional[int] = None,
-    ) -> list[dict[str, Any]]:
+    ) -> list[TopologySummary]:
         statement = select(Topology).order_by(desc(Topology.created_at))
         if status:
             statement = statement.where(Topology.status == status)
@@ -59,9 +56,7 @@ class TopologyCoreMixin:
         async with self._session() as session:
             result = await session.execute(statement)
             return [
-                _deserialize_json_fields(
-                    r.model_dump(mode="json"), ("config_snapshot",)
-                )
+                TopologySummary.model_validate(r.model_dump(mode="json"))
                 for r in result.scalars().all()
             ]
 
@@ -140,15 +135,13 @@ class TopologyCoreMixin:
             await session.commit()
             return True
 
-    async def list_topologies_needing_resync(self) -> list[dict[str, Any]]:
+    async def list_topologies_needing_resync(self) -> list[TopologySummary]:
         async with self._session() as session:
             result = await session.execute(
                 select(Topology).where(Topology.needs_resync == True)  # noqa: E712
             )
             return [
-                _deserialize_json_fields(
-                    r.model_dump(mode="json"), ("config_snapshot",)
-                )
+                TopologySummary.model_validate(r.model_dump(mode="json"))
                 for r in result.scalars().all()
             ]
 

decnet/web/db/sqlmodel_repo/topology/deckies.py

@@ -8,6 +8,7 @@ from typing import Any, Optional
 from sqlalchemy import asc, select, text, update
 
 from decnet.web.db.models import TopologyDecky
+from decnet.web.db.models.topology import DeckyRow
 from decnet.web.db.sqlmodel_repo._helpers import (
     _deserialize_json_fields,
     _serialize_json_fields,
@@ -110,7 +111,7 @@ class TopologyDeckiesMixin:
 
     async def list_topology_deckies(
         self, topology_id: str
-    ) -> list[dict[str, Any]]:
+    ) -> list[DeckyRow]:
         async with self._session() as session:
             result = await session.execute(
                 select(TopologyDecky)
@@ -118,8 +119,10 @@ class TopologyDeckiesMixin:
                 .order_by(asc(TopologyDecky.name))
             )
             return [
-                _deserialize_json_fields(
-                    r.model_dump(mode="json"), ("services", "decky_config")
+                DeckyRow.model_validate(
+                    _deserialize_json_fields(
+                        r.model_dump(mode="json"), ("services", "decky_config")
+                    )
                 )
                 for r in result.scalars().all()
             ]

decnet/web/db/sqlmodel_repo/topology/edges.py

@@ -6,6 +6,7 @@ from typing import Any, Optional
 from sqlalchemy import desc, select, text
 
 from decnet.web.db.models import TopologyEdge, TopologyStatusEvent
+from decnet.web.db.models.topology import EdgeRow
 
 
 class TopologyEdgesMixin:
@@ -60,12 +61,12 @@ class TopologyEdgesMixin:
 
     async def list_topology_edges(
         self, topology_id: str
-    ) -> list[dict[str, Any]]:
+    ) -> list[EdgeRow]:
         async with self._session() as session:
             result = await session.execute(
                 select(TopologyEdge).where(TopologyEdge.topology_id == topology_id)
             )
-            return [r.model_dump(mode="json") for r in result.scalars().all()]
+            return [EdgeRow.model_validate(r.model_dump(mode="json")) for r in result.scalars().all()]
 
     async def list_topology_status_events(
         self, topology_id: str, limit: int = 100

decnet/web/db/sqlmodel_repo/topology/lans.py

@@ -6,6 +6,7 @@ from typing import Any, Optional
 from sqlalchemy import asc, select, text, update
 
 from decnet.web.db.models import LAN, TopologyEdge
+from decnet.web.db.models.topology import LANRow
 
 
 class LansMixin:
@@ -117,9 +118,9 @@ class LansMixin:
 
     async def list_lans_for_topology(
         self, topology_id: str
-    ) -> list[dict[str, Any]]:
+    ) -> list[LANRow]:
         async with self._session() as session:
             result = await session.execute(
                 select(LAN).where(LAN.topology_id == topology_id).order_by(asc(LAN.name))
             )
-            return [r.model_dump(mode="json") for r in result.scalars().all()]
+            return [LANRow.model_validate(r.model_dump(mode="json")) for r in result.scalars().all()]

decnet/web/router/swarm/api_heartbeat.py

@@ -135,8 +135,8 @@ async def _reconcile_topology_report(
     reported_hash = (reported or {}).get("applied_version_hash")
 
     for topo in mine:
-        tid = topo["id"]
-        if topo.get("needs_resync"):
+        tid = topo.id
+        if topo.needs_resync:
             continue
         expected: Optional[str] = None
         if reported_id == tid and reported_hash:

decnet/web/router/topology/_guards.py

@@ -1,8 +1,6 @@
 """Shared helpers for the Phase-3 child-CRUD routes."""
 from __future__ import annotations
 
-from typing import Any
-
 from fastapi import HTTPException
 
 from decnet.topology.status import (
@@ -10,17 +8,18 @@ from decnet.topology.status import (
     TopologyStatus,
     VersionConflict,
 )
+from decnet.web.db.models.topology import TopologySummary
 from decnet.web.dependencies import repo
 
 
-async def get_topology_or_404(topology_id: str) -> dict[str, Any]:
+async def get_topology_or_404(topology_id: str) -> TopologySummary:
     topo = await repo.get_topology(topology_id)
     if topo is None:
         raise HTTPException(status_code=404, detail="Topology not found")
     return topo
 
 
-async def assert_pending_or_409(topology_id: str) -> dict[str, Any]:
+async def assert_pending_or_409(topology_id: str) -> TopologySummary:
     """Ensure the topology exists and is in ``pending`` state.
 
     The repo layer enforces the same rule inside mutation methods, but the
@@ -28,11 +27,11 @@ async def assert_pending_or_409(topology_id: str) -> dict[str, Any]:
     the pre-condition before any side effect.
     """
     topo = await get_topology_or_404(topology_id)
-    if topo["status"] != TopologyStatus.PENDING:
+    if topo.status != TopologyStatus.PENDING:
         raise HTTPException(
             status_code=409,
             detail=(
-                f"Topology is {topo['status']!r}; free-form child edits are "
+                f"Topology is {topo.status!r}; free-form child edits are "
                 f"pending-only.  Use the mutation queue for active topologies."
             ),
         )

decnet/web/router/topology/api_catalog.py

@@ -164,13 +164,13 @@ async def api_next_ip(
     if await repo.get_topology(topology_id) is None:
         raise HTTPException(status_code=404, detail="Topology not found")
     lans = await repo.list_lans_for_topology(topology_id)
-    lan = next((ln for ln in lans if ln["id"] == lan_id), None)
+    lan = next((ln for ln in lans if ln.id == lan_id), None)
     if lan is None:
         raise HTTPException(status_code=404, detail="LAN not found")
     deckies = await repo.list_topology_deckies(topology_id)
-    alloc = IPAllocator(subnet=lan["subnet"])
+    alloc = IPAllocator(subnet=lan.subnet)
     for d in deckies:
-        ip = (d.get("decky_config") or {}).get("ips_by_lan", {}).get(lan["name"])
+        ip = (d.decky_config or {}).get("ips_by_lan", {}).get(lan.name)
         if ip:
             try:
                 alloc.reserve(ip)
@@ -180,4 +180,4 @@ async def api_next_ip(
         ip = alloc.next_free()
     except AllocatorExhausted as e:
         raise HTTPException(status_code=409, detail=str(e))
-    return NextIPResponse(subnet=lan["subnet"], ip=ip)
+    return NextIPResponse(subnet=lan.subnet, ip=ip)

decnet/web/router/topology/api_decky_crud.py

@@ -58,10 +58,10 @@ async def api_create_decky(
         raise map_repo_exception(exc) from exc
 
     rows = await repo.list_topology_deckies(topology_id)
-    row = next((r for r in rows if r["uuid"] == decky_uuid), None)
+    row = next((r for r in rows if r.uuid == decky_uuid), None)
     if row is None:  # pragma: no cover
         raise HTTPException(status_code=500, detail="Decky insert vanished")
-    return DeckyRow(**row)
+    return row
 
 
 @router.patch(
@@ -99,10 +99,10 @@ async def api_update_decky(
         raise HTTPException(status_code=404, detail=str(exc)) from exc
 
     rows = await repo.list_topology_deckies(topology_id)
-    row = next((r for r in rows if r["uuid"] == decky_uuid), None)
+    row = next((r for r in rows if r.uuid == decky_uuid), None)
     if row is None:
         raise HTTPException(status_code=404, detail="Decky not found")
-    return DeckyRow(**row)
+    return row
 
 
 @router.delete(
@@ -126,7 +126,7 @@ async def api_delete_decky(
     await assert_pending_or_409(topology_id)
 
     rows = await repo.list_topology_deckies(topology_id)
-    if not any(r["uuid"] == decky_uuid for r in rows):
+    if not any(r.uuid == decky_uuid for r in rows):
         raise HTTPException(status_code=404, detail="Decky not found")
 
     try:

decnet/web/router/topology/api_delete_topology.py

@@ -36,11 +36,11 @@ async def api_delete_topology(
     topo = await repo.get_topology(topology_id)
     if topo is None:
         raise HTTPException(status_code=404, detail="Topology not found")
-    if topo["status"] not in _DELETABLE:
+    if topo.status not in _DELETABLE:
         raise HTTPException(
             status_code=409,
             detail=(
-                f"Topology is {topo['status']!r}; teardown to 'torn_down' "
+                f"Topology is {topo.status!r}; teardown to 'torn_down' "
                 f"before delete."
             ),
         )

decnet/web/router/topology/api_deploy_topology.py

@@ -63,11 +63,11 @@ async def api_deploy_topology(
     topo = await repo.get_topology(topology_id)
     if topo is None:
         raise HTTPException(status_code=404, detail="Topology not found")
-    if topo["status"] != TopologyStatus.PENDING:
+    if topo.status != TopologyStatus.PENDING:
         raise HTTPException(
             status_code=409,
             detail=(
-                f"Topology is {topo['status']!r}; only 'pending' topologies "
+                f"Topology is {topo.status!r}; only 'pending' topologies "
                 f"can be deployed."
             ),
         )

decnet/web/router/topology/api_edge_crud.py

@@ -46,13 +46,13 @@ async def api_create_edge(
 
     # Referential integrity: decky + LAN must belong to this topology.
     deckies = await repo.list_topology_deckies(topology_id)
-    if not any(d["uuid"] == body.decky_uuid for d in deckies):
+    if not any(d.uuid == body.decky_uuid for d in deckies):
         raise HTTPException(
             status_code=400,
             detail=f"decky {body.decky_uuid!r} not in topology {topology_id!r}",
         )
     lans = await repo.list_lans_for_topology(topology_id)
-    if not any(r["id"] == body.lan_id for r in lans):
+    if not any(r.id == body.lan_id for r in lans):
         raise HTTPException(
             status_code=400,
             detail=f"lan {body.lan_id!r} not in topology {topology_id!r}",
@@ -73,10 +73,10 @@ async def api_create_edge(
         raise map_repo_exception(exc) from exc
 
     edges = await repo.list_topology_edges(topology_id)
-    row = next((e for e in edges if e["id"] == edge_id), None)
+    row = next((e for e in edges if e.id == edge_id), None)
     if row is None:  # pragma: no cover
         raise HTTPException(status_code=500, detail="Edge insert vanished")
-    return EdgeRow(**row)
+    return row
 
 
 @router.delete(
@@ -100,7 +100,7 @@ async def api_delete_edge(
     await assert_pending_or_409(topology_id)
 
     edges = await repo.list_topology_edges(topology_id)
-    if not any(e["id"] == edge_id for e in edges):
+    if not any(e.id == edge_id for e in edges):
         raise HTTPException(status_code=404, detail="Edge not found")
 
     try:

decnet/web/router/topology/api_events.py

@@ -69,7 +69,7 @@ async def api_topology_events(
     # GET /topologies/{id}/mutations). Adding a new event family here
     # requires a threat-model review for F6/I (role leakage).
     topo = await get_topology_or_404(topology_id)
-    snapshot_status = topo["status"]
+    snapshot_status = topo.status
     in_flight: list[dict] = []
     for state in _IN_FLIGHT_STATES:
         in_flight.extend(await repo.list_topology_mutations(topology_id, state=state))

decnet/web/router/topology/api_lan_crud.py

@@ -73,11 +73,11 @@ async def api_create_lan(
         raise map_repo_exception(exc) from exc
 
     rows = await repo.list_lans_for_topology(topology_id)
-    row = next((r for r in rows if r["id"] == lan_id), None)
+    row = next((r for r in rows if r.id == lan_id), None)
     if row is None:  # pragma: no cover — would mean insert vanished
         raise HTTPException(status_code=500, detail="LAN insert vanished")
 
-    return LANRow(**row)
+    return row
 
 
 @router.patch(
@@ -115,10 +115,10 @@ async def api_update_lan(
         raise HTTPException(status_code=404, detail=str(exc)) from exc
 
     rows = await repo.list_lans_for_topology(topology_id)
-    row = next((r for r in rows if r["id"] == lan_id), None)
+    row = next((r for r in rows if r.id == lan_id), None)
     if row is None:
         raise HTTPException(status_code=404, detail="LAN not found")
-    return LANRow(**row)
+    return row
 
 
 @router.delete(
@@ -142,7 +142,7 @@ async def api_delete_lan(
     await assert_pending_or_409(topology_id)
 
     rows = await repo.list_lans_for_topology(topology_id)
-    if not any(r["id"] == lan_id for r in rows):
+    if not any(r.id == lan_id for r in rows):
         raise HTTPException(status_code=404, detail="LAN not found")
 
     try:

decnet/web/router/topology/api_mutations.py

@@ -63,11 +63,11 @@ async def api_enqueue_mutation(
     _admin: dict = Depends(require_admin),
 ) -> MutationEnqueueResponse:
     topo = await get_topology_or_404(topology_id)
-    if topo["status"] not in _MUTATABLE:
+    if topo.status not in _MUTATABLE:
         raise HTTPException(
             status_code=409,
             detail=(
-                f"Topology is {topo['status']!r}; the mutation queue is "
+                f"Topology is {topo.status!r}; the mutation queue is "
                 f"only open for 'active' or 'degraded' topologies.  Use "
                 f"child-CRUD endpoints while pending."
             ),

decnet/web/router/topology/api_personas.py

@@ -54,13 +54,13 @@ async def list_topology_personas(
     topo = await repo.get_topology(topology_id)
     if topo is None:
         raise HTTPException(status_code=404, detail="Topology not found")
-    language_default = topo.get("language_default") or "en"
+    language_default = topo.language_default or "en"
     personas = parse_personas(
-        topo.get("email_personas"), language_default=language_default,
+        topo.email_personas, language_default=language_default,
     )
     return {
         "topology_id": topology_id,
-        "topology_name": topo.get("name", ""),
+        "topology_name": topo.name,
         "language_default": language_default,
         "personas": _serialize(personas),
     }
@@ -100,7 +100,7 @@ async def replace_topology_personas(
     topo = await repo.get_topology(topology_id)
     if topo is None:
         raise HTTPException(status_code=404, detail="Topology not found")
-    language_default = topo.get("language_default") or "en"
+    language_default = topo.language_default or "en"
 
     parsed = parse_personas(raw, language_default=language_default)
     if raw and not parsed:
@@ -125,7 +125,7 @@ async def replace_topology_personas(
     )
     return {
         "topology_id": topology_id,
-        "topology_name": topo.get("name", ""),
+        "topology_name": topo.name,
         "language_default": language_default,
         "personas": serialized,
     }

decnet/web/router/topology/api_teardown_topology.py

@@ -66,11 +66,11 @@ async def api_teardown_topology(
     topo = await repo.get_topology(topology_id)
     if topo is None:
         raise HTTPException(status_code=404, detail="Topology not found")
-    if topo["status"] not in _TEARDOWNABLE:
+    if topo.status not in _TEARDOWNABLE:
         raise HTTPException(
             status_code=409,
             detail=(
-                f"Topology is {topo['status']!r}; cannot teardown "
+                f"Topology is {topo.status!r}; cannot teardown "
                 f"(allowed from: {sorted(_TEARDOWNABLE)})."
             ),
         )