feat: add simulation clocks and VM transitions

app/simulation/clock.py

@@ -0,0 +1,61 @@
+"""Injectable simulation clocks; task leases deliberately do not use these."""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime, timedelta
+from typing import Protocol
+
+
+class Clock(Protocol):
+    async def now(self) -> datetime: ...
+
+    async def sleep(self, seconds: float) -> None: ...
+
+
+class RealClock:
+    async def now(self) -> datetime:
+        return datetime.now(UTC)
+
+    async def sleep(self, seconds: float) -> None:
+        await asyncio.sleep(seconds)
+
+
+class AcceleratedClock:
+    def __init__(self, scale: float) -> None:
+        if scale <= 0:
+            raise ValueError("clock scale must be positive")
+        self._scale = scale
+
+    async def now(self) -> datetime:
+        return datetime.now(UTC)
+
+    async def sleep(self, seconds: float) -> None:
+        await asyncio.sleep(seconds / self._scale)
+
+
+class ManualClock:
+    def __init__(self, initial: datetime) -> None:
+        if initial.tzinfo is None:
+            raise ValueError("manual clock requires timezone-aware time")
+        self._now = initial
+        self._condition = asyncio.Condition()
+
+    async def now(self) -> datetime:
+        async with self._condition:
+            return self._now
+
+    async def sleep(self, seconds: float) -> None:
+        if seconds < 0:
+            raise ValueError("sleep duration cannot be negative")
+        async with self._condition:
+            target = self._now + timedelta(seconds=seconds)
+            await self._condition.wait_for(lambda: self._now >= target)
+
+    async def advance(self, seconds: float) -> datetime:
+        if seconds < 0:
+            raise ValueError("clock cannot move backwards")
+        async with self._condition:
+            self._now += timedelta(seconds=seconds)
+            self._condition.notify_all()
+            return self._now

app/simulation/scenarios.py

@@ -0,0 +1,49 @@
+"""Seeded deterministic fault-rule evaluation."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class FaultContext:
+    method: str
+    path: str
+    principal: str | None = None
+    node: str | None = None
+    vmid: str | None = None
+    call_number: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class FaultRule:
+    kind: str
+    probability: float = 1.0
+    method: str | None = None
+    path_prefix: str | None = None
+    principal: str | None = None
+    node: str | None = None
+    vmid: str | None = None
+    call_number: int | None = None
+
+    def __post_init__(self) -> None:
+        if not 0 <= self.probability <= 1:
+            raise ValueError("fault probability must be between zero and one")
+
+
+def matches(rule: FaultRule, context: FaultContext, seed: int) -> bool:
+    filters = (
+        (rule.method, context.method),
+        (rule.principal, context.principal),
+        (rule.node, context.node),
+        (rule.vmid, context.vmid),
+        (rule.call_number, context.call_number),
+    )
+    if any(expected is not None and expected != actual for expected, actual in filters):
+        return False
+    if rule.path_prefix is not None and not context.path.startswith(rule.path_prefix):
+        return False
+    material = f"{seed}:{rule.kind}:{context.method}:{context.path}:{context.call_number}"
+    sample = int.from_bytes(hashlib.sha256(material.encode()).digest()[:8], "big") / 2**64
+    return sample < rule.probability

app/simulation/transitions.py

@@ -0,0 +1,63 @@
+"""Explicit virtual-machine state machine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from app.simulation.clock import Clock
+
+
+class VmState(StrEnum):
+    STOPPED = "stopped"
+    STARTING = "starting"
+    RUNNING = "running"
+    PAUSING = "pausing"
+    PAUSED = "paused"
+    RESUMING = "resuming"
+    STOPPING = "stopping"
+    MIGRATING = "migrating"
+    SNAPSHOTTING = "snapshotting"
+    BACKING_UP = "backing_up"
+    ERROR = "error"
+
+
+class InvalidTransitionError(ValueError):
+    pass
+
+
+TRANSITIONS: dict[tuple[VmState, str], tuple[VmState, VmState]] = {
+    (VmState.STOPPED, "start"): (VmState.STARTING, VmState.RUNNING),
+    (VmState.RUNNING, "stop"): (VmState.STOPPING, VmState.STOPPED),
+    (VmState.RUNNING, "pause"): (VmState.PAUSING, VmState.PAUSED),
+    (VmState.PAUSED, "resume"): (VmState.RESUMING, VmState.RUNNING),
+    (VmState.RUNNING, "migrate"): (VmState.MIGRATING, VmState.RUNNING),
+    (VmState.STOPPED, "migrate"): (VmState.MIGRATING, VmState.STOPPED),
+    (VmState.RUNNING, "snapshot"): (VmState.SNAPSHOTTING, VmState.RUNNING),
+    (VmState.STOPPED, "snapshot"): (VmState.SNAPSHOTTING, VmState.STOPPED),
+    (VmState.RUNNING, "backup"): (VmState.BACKING_UP, VmState.RUNNING),
+    (VmState.STOPPED, "backup"): (VmState.BACKING_UP, VmState.STOPPED),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Transition:
+    operation: str
+    before: VmState
+    intermediate: VmState
+    after: VmState
+
+
+def plan_transition(state: VmState, operation: str) -> Transition:
+    states = TRANSITIONS.get((state, operation))
+    if states is None:
+        raise InvalidTransitionError(f"cannot {operation} VM while it is {state}")
+    return Transition(operation, state, states[0], states[1])
+
+
+async def execute_transition(
+    state: VmState, operation: str, clock: Clock, duration_seconds: float
+) -> tuple[VmState, VmState]:
+    transition = plan_transition(state, operation)
+    await clock.sleep(duration_seconds)
+    return transition.intermediate, transition.after