feat(mazenet): topology package — config, status machine, generator, persistence

Adds decnet/topology/ with:

- config.TopologyConfig: pydantic model driving generation (depth,
  branching_factor, deckies_per_lan_min/max, bridge_forward_probability,
  cross_edge_probability, subnet_base_prefix, service selection, seed).
  Emits GeneratedTopology dataclass (lans, deckies, edges).

- status.TopologyStatus + assert_transition: seven-state machine with
  an explicit legal-transition table.  torn_down is terminal; degraded
  is schema-reserved for future Healer use.

- generator.generate: deterministic DAG generation under config.seed.
  Builds a tree of LANs (DMZ at root), plants deckies in each LAN,
  promotes one decky per non-DMZ LAN to a parent bridge, and rolls
  cross-edges per cross_edge_probability for DAG shape.

- persistence: persist() writes a plan to the repo as pending;
  transition_status() enforces state-machine legality; hydrate() loads
  topology + children into a single dict.

Covered by tests/topology/{test_status,test_generator,test_persistence}.

tests/topology/test_generator.py

@@ -0,0 +1,137 @@
+"""MazeNET generator determinism + DAG shape tests."""
+from __future__ import annotations
+
+from collections import Counter
+
+import pytest
+
+from decnet.topology.config import TopologyConfig
+from decnet.topology.generator import generate
+
+
+def _cfg(**kw) -> TopologyConfig:
+    base = dict(
+        name="test",
+        depth=3,
+        branching_factor=2,
+        deckies_per_lan_min=2,
+        deckies_per_lan_max=2,
+        bridge_forward_probability=1.0,
+        cross_edge_probability=0.0,
+        randomize_services=True,
+        seed=42,
+    )
+    base.update(kw)
+    return TopologyConfig(**base)
+
+
+def test_seed_is_deterministic():
+    a = generate(_cfg())
+    b = generate(_cfg())
+    # Same structure: same LAN names, same decky names, same edge set.
+    assert [lan.name for lan in a.lans] == [lan.name for lan in b.lans]
+    assert [d.name for d in a.deckies] == [d.name for d in b.deckies]
+    assert [(d.name, sorted(d.services)) for d in a.deckies] == [
+        (d.name, sorted(d.services)) for d in b.deckies
+    ]
+    assert sorted((e.decky_name, e.lan_name) for e in a.edges) == sorted(
+        (e.decky_name, e.lan_name) for e in b.edges
+    )
+
+
+def test_different_seed_yields_different_structure():
+    a = generate(_cfg(seed=1))
+    b = generate(_cfg(seed=2))
+    # With modest depth/branching, at least one of structure, service
+    # assignment, or edge count will differ — fail only if everything is
+    # byte-identical, which would indicate the seed is being ignored.
+    a_sig = (
+        [lan.name for lan in a.lans],
+        [(d.name, sorted(d.services)) for d in a.deckies],
+        sorted((e.decky_name, e.lan_name) for e in a.edges),
+    )
+    b_sig = (
+        [lan.name for lan in b.lans],
+        [(d.name, sorted(d.services)) for d in b.deckies],
+        sorted((e.decky_name, e.lan_name) for e in b.edges),
+    )
+    assert a_sig != b_sig
+
+
+def test_dmz_is_exactly_one_lan():
+    t = generate(_cfg())
+    dmz = [lan for lan in t.lans if lan.is_dmz]
+    assert len(dmz) == 1
+    assert dmz[0].parent is None
+    assert dmz[0].name == "LAN-00"
+
+
+def test_every_non_dmz_lan_has_exactly_one_bridge_into_parent():
+    t = generate(_cfg(branching_factor=2, depth=3))
+    # For each non-DMZ LAN, find the decky that is multi-homed to its parent.
+    for lan in t.lans:
+        if lan.is_dmz:
+            continue
+        bridges_to_parent = [
+            d for d in t.deckies
+            if lan.name in d.ips_by_lan and lan.parent in d.ips_by_lan
+        ]
+        assert len(bridges_to_parent) >= 1, (
+            f"{lan.name} has no bridge into parent {lan.parent}"
+        )
+
+
+def test_cross_edge_probability_zero_yields_tree():
+    """With cross_edge_probability=0, a decky is bridged only to its home
+    LAN and (if it's the chosen bridge) its parent LAN — never to a
+    sibling or cousin.  Validates by checking no decky is connected to
+    both a parent AND a non-parent non-home LAN."""
+    t = generate(_cfg(cross_edge_probability=0.0))
+    lans_by_name = {lan.name: lan for lan in t.lans}
+    for d in t.deckies:
+        if len(d.ips_by_lan) <= 1:
+            continue
+        # Home LAN = first membership.  Other memberships must all be
+        # the parent of the home LAN, i.e. a single parent bridge.
+        home = next(iter(d.ips_by_lan))
+        others = [name for name in list(d.ips_by_lan.keys())[1:]]
+        parent = lans_by_name[home].parent
+        assert all(o == parent for o in others), (
+            f"tree mode but decky {d.name} bridges {home}→{others} (parent={parent})"
+        )
+
+
+def test_cross_edge_probability_one_produces_cross_edges_over_runs():
+    """With probability=1, every non-DMZ LAN rolls a cross-edge (may be
+    skipped if no valid peer), so across a moderately branching topology
+    we expect ≥1 cross-edge."""
+    t = generate(_cfg(cross_edge_probability=1.0, depth=3, branching_factor=3))
+    lans_by_name = {lan.name: lan for lan in t.lans}
+    cross_edges = 0
+    for d in t.deckies:
+        if len(d.ips_by_lan) < 2:
+            continue
+        home = next(iter(d.ips_by_lan))
+        others = list(d.ips_by_lan.keys())[1:]
+        parent = lans_by_name[home].parent
+        for o in others:
+            if o != parent:
+                cross_edges += 1
+    assert cross_edges >= 1
+
+
+def test_every_decky_has_at_least_one_edge():
+    t = generate(_cfg())
+    edge_deckies = Counter(e.decky_name for e in t.edges)
+    for d in t.deckies:
+        assert edge_deckies[d.name] >= 1
+
+
+def test_dmz_has_exactly_one_decky():
+    t = generate(_cfg(deckies_per_lan_min=5, deckies_per_lan_max=5))
+    dmz_edges = [e for e in t.edges if e.lan_name == "LAN-00"]
+    # The DMZ LAN itself gets 1 decky + possibly acts as parent for
+    # bridge deckies from LAN-01/LAN-02 etc.  The "home" decky count
+    # should be exactly 1.
+    home_only = [e for e in dmz_edges if not e.is_bridge]
+    assert len(home_only) == 1

tests/topology/test_persistence.py

@@ -0,0 +1,91 @@
+"""MazeNET persistence-layer tests: generator → repo → hydrate roundtrip."""
+import pytest
+
+from decnet.topology.config import TopologyConfig
+from decnet.topology.generator import generate
+from decnet.topology.persistence import (
+    hydrate,
+    persist,
+    transition_status,
+)
+from decnet.topology.status import TopologyStatus, TopologyStatusError
+from decnet.web.db.factory import get_repository
+
+
+@pytest.fixture
+async def repo(tmp_path):
+    r = get_repository(db_path=str(tmp_path / "persist.db"))
+    await r.initialize()
+    return r
+
+
+def _config(**kw) -> TopologyConfig:
+    base = dict(
+        name="roundtrip",
+        depth=2,
+        branching_factor=2,
+        deckies_per_lan_min=1,
+        deckies_per_lan_max=2,
+        cross_edge_probability=0.0,
+        randomize_services=True,
+        seed=7,
+    )
+    base.update(kw)
+    return TopologyConfig(**base)
+
+
+@pytest.mark.anyio
+async def test_persist_then_hydrate(repo):
+    plan = generate(_config())
+    tid = await persist(repo, plan)
+
+    hydrated = await hydrate(repo, tid)
+    assert hydrated is not None
+    assert hydrated["topology"]["name"] == "roundtrip"
+    assert hydrated["topology"]["status"] == TopologyStatus.PENDING
+    assert len(hydrated["lans"]) == len(plan.lans)
+    assert len(hydrated["deckies"]) == len(plan.deckies)
+    assert len(hydrated["edges"]) == len(plan.edges)
+
+    # LANs round-trip with their DMZ flag and subnet.
+    by_name = {lan["name"]: lan for lan in hydrated["lans"]}
+    for planned in plan.lans:
+        assert by_name[planned.name]["subnet"] == planned.subnet
+        assert by_name[planned.name]["is_dmz"] == planned.is_dmz
+
+    # Deckies round-trip their services as a list, not a string.
+    for d in hydrated["deckies"]:
+        assert isinstance(d["services"], list)
+
+
+@pytest.mark.anyio
+async def test_transition_status_enforces_legality(repo):
+    plan = generate(_config())
+    tid = await persist(repo, plan)
+
+    await transition_status(repo, tid, TopologyStatus.DEPLOYING, reason="go")
+    await transition_status(repo, tid, TopologyStatus.ACTIVE)
+    topo = await repo.get_topology(tid)
+    assert topo["status"] == TopologyStatus.ACTIVE
+
+    # Can't go from active directly back to pending.
+    with pytest.raises(TopologyStatusError):
+        await transition_status(repo, tid, TopologyStatus.PENDING)
+
+    # Unknown topology raises ValueError, not silent no-op.
+    with pytest.raises(ValueError):
+        await transition_status(repo, "does-not-exist", TopologyStatus.ACTIVE)
+
+
+@pytest.mark.anyio
+async def test_hydrate_missing_topology(repo):
+    assert await hydrate(repo, "no-such-id") is None
+
+
+@pytest.mark.anyio
+async def test_config_snapshot_preserves_seed(repo):
+    plan = generate(_config(seed=12345))
+    tid = await persist(repo, plan)
+    topo = await repo.get_topology(tid)
+    assert topo["config_snapshot"]["seed"] == 12345
+    assert topo["config_snapshot"]["depth"] == 2

tests/topology/test_status.py

@@ -0,0 +1,55 @@
+"""MazeNET status state-machine tests.
+
+Every legal transition declared in the plan is permitted; every other
+pair (including self-loops and unknowns) must raise.
+"""
+import pytest
+from decnet.topology.status import (
+    TopologyStatus,
+    TopologyStatusError,
+    assert_transition,
+    legal_next,
+)
+
+LEGAL = {
+    (TopologyStatus.PENDING, TopologyStatus.DEPLOYING),
+    (TopologyStatus.PENDING, TopologyStatus.TORN_DOWN),
+    (TopologyStatus.DEPLOYING, TopologyStatus.ACTIVE),
+    (TopologyStatus.DEPLOYING, TopologyStatus.FAILED),
+    (TopologyStatus.DEPLOYING, TopologyStatus.DEGRADED),
+    (TopologyStatus.DEPLOYING, TopologyStatus.TEARING_DOWN),
+    (TopologyStatus.ACTIVE, TopologyStatus.DEGRADED),
+    (TopologyStatus.ACTIVE, TopologyStatus.TEARING_DOWN),
+    (TopologyStatus.DEGRADED, TopologyStatus.ACTIVE),
+    (TopologyStatus.DEGRADED, TopologyStatus.TEARING_DOWN),
+    (TopologyStatus.FAILED, TopologyStatus.TEARING_DOWN),
+    (TopologyStatus.TEARING_DOWN, TopologyStatus.TORN_DOWN),
+    (TopologyStatus.TEARING_DOWN, TopologyStatus.DEGRADED),
+}
+
+
+def test_every_legal_transition_permitted():
+    for cur, nxt in LEGAL:
+        assert_transition(cur, nxt)  # no raise
+
+
+def test_every_illegal_transition_raises():
+    for cur in TopologyStatus.ALL:
+        for nxt in TopologyStatus.ALL:
+            if (cur, nxt) in LEGAL:
+                continue
+            with pytest.raises(TopologyStatusError):
+                assert_transition(cur, nxt)
+
+
+def test_torn_down_is_terminal():
+    assert legal_next(TopologyStatus.TORN_DOWN) == frozenset()
+
+
+def test_unknown_status_raises():
+    with pytest.raises(TopologyStatusError):
+        assert_transition("pending", "bogus")
+    with pytest.raises(TopologyStatusError):
+        assert_transition("bogus", "active")
+    with pytest.raises(TopologyStatusError):
+        legal_next("bogus")