feat(topology): optimistic concurrency via Topology.version + expected_version

MazeNET phase 2 step 4. Readies the repo layer for concurrent editors
(web canvas + CLI + mutator) without lost-write races.

- Topology.version: monotonically bumped on supervised child-row writes.
- VersionConflict exception carries {current, expected} for the UI.
- _check_and_bump_version helper reads Topology in the same session,
  compares against expected_version, raises on mismatch, bumps on match.
  Commit happens in the caller's existing transaction so check+bump+write
  are atomic per mutation.
- add_lan / update_lan / add_topology_decky / update_topology_decky /
  add_topology_edge accept expected_version=None by default, preserving
  every existing caller's behavior.

When expected_version is None, no check runs and version stays put —
internal callers (persist) that don't care about concurrency keep
working unchanged.
This commit is contained in:
2026-04-20 17:47:28 -04:00
parent 2544d0294a
commit e475c0957e
4 changed files with 231 additions and 5 deletions

View File

@@ -53,6 +53,22 @@ class TopologyStatusError(ValueError):
"""Raised when an illegal topology status transition is attempted."""
class VersionConflict(RuntimeError):
"""Raised when a topology write is supplied a stale ``expected_version``.
Optimistic concurrency guard: the caller passed the version it last
observed, and the topology has since been mutated by someone else.
The caller should re-read and retry.
"""
def __init__(self, *, current: int, expected: int) -> None:
self.current = current
self.expected = expected
super().__init__(
f"topology version conflict: expected {expected}, current is {current}"
)
def assert_transition(current: str, new: str) -> None:
"""Validate ``current → new`` or raise :class:`TopologyStatusError`."""
if current not in TopologyStatus.ALL: