dosync 0.4.1__py3-none-any.whl

dosync/operation_guards.py

@@ -0,0 +1,228 @@
+"""
+DoSync — Operation guards (real-time in-flight monitoring for composite operations).
+====================================================================================
+
+The PolicyEngine is PRE-FLIGHT AUTHORIZATION: it judges a plan once, before dispatch,
+and answers ALLOW/BLOCK/CONFIRM/MODIFY. These guards are IN-FLIGHT MONITORING: the
+supervisor calls them on every tick while a composite operation is live, and they
+answer "keep going" (None) or "abort, here's why" (a reason string). Two different
+safety systems for two different moments — the panel was explicit that they must not
+be merged (incompatible contracts), but they SHARE the geofence calculation (in
+dosync/geo.py) so the formula never lives in two copies.
+
+This is the brain watching the body's vital signs during the trip — not the
+environment (no obstacle/“tree” sensing; that needs sensors the body does not have
+yet), but everything the vehicle itself reports: position (still inside the fence?),
+link (still alive?), mode (did a human take over?), battery, time-in-state.
+
+DESIGN (validated by the expert panel):
+  * Each guard is an independent, composable object with a name and a check(comp)
+    method returning a reason-or-None. A GuardSet runs them in order; the first to
+    fire wins (like the PolicyEngine's first-block-wins, shared PATTERN, separate
+    component).
+  * The guards consume a CONTEXT object the supervisor refreshes from reconciled
+    state + telemetry each tick — they never read the raw telemetry queue (that is
+    the consumer's job; guards are decision, not perception).
+  * First version: DETECT and report a clear abort reason. Differentiated REACTIONS
+    (link-loss → return home; human took control → let go; battery → land here) are
+    a documented second layer; the supervisor's safe default today is to abort, and
+    the caller routes the vehicle home. Keeping the first version to "detect + abort
+    with a clear reason" is honest and already large.
+  * The human-takeover guard is special and the panel flagged it: when a human is
+    flying, the right behavior is NOT to fight for control. The guard fires (so the
+    supervisor stops dispatching), and the safe meaning is "let go," distinct from a
+    fault. This is recorded in the reason so the second-layer reaction can tell them
+    apart later.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .geo import is_within_perimeter
+
+
+@dataclass
+class GuardContext:
+    """A snapshot the supervisor refreshes each tick from reconciled state +
+    telemetry. The guards read THIS, never the raw queue. Every field is optional so
+    a deployment that cannot supply a signal simply leaves it None and the
+    corresponding guard abstains (it never invents a reading)."""
+    device_id: str
+    # Current reported position (from telemetry). None = unknown this tick.
+    lat: Optional[float] = None
+    lon: Optional[float] = None
+    alt: Optional[float] = None
+    # Seconds since the last telemetry message arrived. None = unknown.
+    seconds_since_telemetry: Optional[float] = None
+    # Whether a human currently holds manual control (operation interrupted).
+    manual_control_active: bool = False
+    # Battery remaining, 0..100. None = unknown.
+    battery_percent: Optional[float] = None
+    # Seconds the current mission step has been running. None = unknown.
+    seconds_in_step: Optional[float] = None
+
+
+class BaseGuard:
+    """A composable in-flight guard. Subclasses implement check(ctx) -> reason|None."""
+
+    @property
+    def name(self) -> str:
+        raise NotImplementedError
+
+    def check(self, ctx: GuardContext) -> Optional[str]:
+        raise NotImplementedError
+
+
+class GeofenceGuard(BaseGuard):
+    """Fires if the vehicle's REPORTED position leaves the permitted perimeter.
+
+    This is the in-flight twin of GeofencePolicy. The policy checks a go_to's TARGET
+    before dispatch; this checks where the vehicle ACTUALLY is, every tick — catching
+    a vehicle blown off course by wind, GPS drift, or any drift the pre-flight check
+    could not foresee. Both call the same is_within_perimeter (dosync/geo.py): one
+    rule, two moments (admission + monitoring). Cinturón y airbag.
+    """
+
+    def __init__(self, center_lat: float, center_lon: float,
+                 max_radius_m: float, max_altitude_m: Optional[float] = None):
+        self._center_lat = center_lat
+        self._center_lon = center_lon
+        self._max_radius_m = max_radius_m
+        self._max_altitude_m = max_altitude_m
+
+    @property
+    def name(self) -> str:
+        return "geofence_in_flight"
+
+    def check(self, ctx: GuardContext) -> Optional[str]:
+        if ctx.lat is None or ctx.lon is None:
+            return None  # no position this tick — abstain, never invent
+        ok, reason = is_within_perimeter(
+            ctx.lat, ctx.lon, self._center_lat, self._center_lon,
+            self._max_radius_m, alt=ctx.alt, max_altitude_m=self._max_altitude_m)
+        if not ok:
+            return f"vehicle left the perimeter in flight: {reason}"
+        return None
+
+
+class LinkLossGuard(BaseGuard):
+    """Fires if telemetry has gone silent for longer than the allowed gap — the link
+    is presumed lost. Silence is not success: a vehicle we cannot hear is a vehicle
+    we are not supervising, and the safe response is to stop and let it come home."""
+
+    def __init__(self, max_silence_s: float = 5.0):
+        self._max_silence_s = max_silence_s
+
+    @property
+    def name(self) -> str:
+        return "link_loss"
+
+    def check(self, ctx: GuardContext) -> Optional[str]:
+        if ctx.seconds_since_telemetry is None:
+            return None
+        if ctx.seconds_since_telemetry > self._max_silence_s:
+            return (f"telemetry link silent for {ctx.seconds_since_telemetry:.0f}s "
+                    f"(> {self._max_silence_s:.0f}s) — link presumed lost")
+        return None
+
+
+class ManualControlGuard(BaseGuard):
+    """Fires when a human has taken manual control. The panel flagged this as
+    special: the right behavior is NOT to fight the pilot. The guard fires so the
+    supervisor stops dispatching; the reason marks it as a handover (not a fault) so a
+    later reaction layer can 'let go' rather than 'return home'."""
+
+    @property
+    def name(self) -> str:
+        return "manual_control"
+
+    def check(self, ctx: GuardContext) -> Optional[str]:
+        if ctx.manual_control_active:
+            return ("human took manual control — DoSync yields (handover, not a "
+                    "fault); stop dispatching and let the pilot fly")
+        return None
+
+
+class BatteryGuard(BaseGuard):
+    """Fires when battery falls below the safe threshold. The vehicle needs enough
+    charge to get home; below the floor, the mission must stop."""
+
+    def __init__(self, min_percent: float = 25.0):
+        self._min_percent = min_percent
+
+    @property
+    def name(self) -> str:
+        return "battery"
+
+    def check(self, ctx: GuardContext) -> Optional[str]:
+        if ctx.battery_percent is None:
+            return None
+        if ctx.battery_percent < self._min_percent:
+            return (f"battery {ctx.battery_percent:.0f}% below the {self._min_percent:.0f}% "
+                    f"floor — not enough charge to continue safely")
+        return None
+
+
+class StepTimeoutGuard(BaseGuard):
+    """Fires when a single step has run longer than allowed — a stalled step that the
+    supervisor's own backstop would also catch, surfaced here as a named guard so the
+    reason is explicit. Belt for the supervisor's suspenders."""
+
+    def __init__(self, max_step_s: float = 120.0):
+        self._max_step_s = max_step_s
+
+    @property
+    def name(self) -> str:
+        return "step_timeout"
+
+    def check(self, ctx: GuardContext) -> Optional[str]:
+        if ctx.seconds_in_step is None:
+            return None
+        if ctx.seconds_in_step > self._max_step_s:
+            return (f"step running for {ctx.seconds_in_step:.0f}s "
+                    f"(> {self._max_step_s:.0f}s) — stalled")
+        return None
+
+
+@dataclass
+class GuardSet:
+    """An ordered, composable set of guards. Runs them in order on each tick; the
+    first to fire wins (shared pattern with the PolicyEngine's first-block-wins,
+    separate component). A deployment registers only the guards it wants — a vehicle
+    with no battery telemetry simply does not add a BatteryGuard.
+
+    The GuardSet exposes a `make_guard_fn(context_provider)` that adapts it to the
+    supervisor's GuardFn hook: the supervisor passes a CompositeOperation, the
+    provider turns it (plus live telemetry) into a GuardContext, and the set runs.
+    """
+    guards: list = field(default_factory=list)
+
+    def add(self, guard: BaseGuard) -> "GuardSet":
+        self.guards.append(guard)
+        return self
+
+    def check(self, ctx: GuardContext) -> Optional[str]:
+        """Run all guards in order; return the first firing guard's reason (prefixed
+        with its name), or None if all pass."""
+        for guard in self.guards:
+            reason = guard.check(ctx)
+            if reason is not None:
+                return f"[{guard.name}] {reason}"
+        return None
+
+    def make_guard_fn(self, context_provider):
+        """Adapt this set to the supervisor's GuardFn(comp) -> reason|None.
+
+        context_provider: a callable taking the live CompositeOperation and returning
+        a GuardContext (built from reconciled state + the latest telemetry). Keeping
+        this injection here means the GuardSet stays pure and testable: tests supply a
+        trivial provider; production supplies one that reads live telemetry.
+        """
+        def guard_fn(comp) -> Optional[str]:
+            ctx = context_provider(comp)
+            if ctx is None:
+                return None
+            return self.check(ctx)
+        return guard_fn

dosync/operation_supervisor.py

@@ -0,0 +1,216 @@
+"""
+DoSync — Operation supervisor (the nervous-system trunk of a composite operation).
+==================================================================================
+
+CompositeOperation is the structure (the ordered steps). RouteComposer fills it with
+geometry. This module is what makes them LIVE: the supervisor drives a composite
+forward, step by step, in a CLOSED LOOP — it dispatches the current step, then WAITS
+for that step's atomic operation to reach a positive terminal state (confirmed
+arrival, never a timer), and only then advances. Between steps it samples continuously
+so guards (next piece) can react in real time.
+
+This is the brain coordinating the body: not "fire the plan and walk away" (open
+loop), but "watch what the body actually did, decide the next move, repeat" (closed
+loop). A waypoint's confirmed arrival is not the end of an instruction — it is
+perception that feeds the next decision.
+
+DESIGN (validated by a multi-pass expert panel incl. a drone manufacturer, a pilot,
+and two systems professors):
+
+  * POLLING at a fixed, CONFIGURABLE cadence — not event subscription. The panel's
+    reasons: (1) the system ALREADY beats — the telemetry consumer
+    (drain_telemetry_once -> apply_telemetry) already runs on a rhythm; the
+    supervisor hangs off that nature instead of bolting on a callback mechanism.
+    (2) Real-time guards (geofence-in-flight, battery, link loss) are INHERENTLY
+    sampling — there is no "geofence-breach event"; you must look. One heartbeat
+    serves both arrival-detection and guards. (3) A predictable cadence is a SAFETY
+    property: you know exactly how often the brain looks at the body.
+
+  * The supervisor POLLS THE RECONCILED STATE, never the raw telemetry queue. The
+    consumer is perception (telemetry -> state); the supervisor is decision (state ->
+    next move). The brain reads the processed body-map, not the raw nerves. This
+    separation is non-negotiable — it is what keeps the nervous system clean.
+
+  * SILENCE IS NOT SUCCESS — inherited end to end. A step only advances when its
+    atomic operation reaches a POSITIVE terminal state (completed). A timeout or a
+    silent gap never advances anything; it is a stall the guards can act on.
+
+  * Dependency-injected dispatch and state-read so the whole loop is unit-testable
+    with NO drone, NO socket, NO hub: the test supplies a fake "dispatch" and a fake
+    "read state", and drives the composite through its lifecycle deterministically.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Optional
+
+from .composite_operations import CompositeOperation, CompositeState, CompositeStep
+
+log = logging.getLogger("dosync.supervisor")
+
+
+# Default sampling cadence. The panel required this be configurable, not hardcoded:
+# a slow inspection can sample wider; a critical maneuver, finer.
+_DEFAULT_POLL_INTERVAL_S = 0.2   # 5 Hz — the brain looks at the body 5x/second
+# Safety ceiling: how long a single step may sit without reaching a terminal atom
+# state before the supervisor treats it as stalled and aborts the composite. This is
+# a backstop, not the primary mechanism (guards are) — silence must never hang forever.
+_DEFAULT_STEP_TIMEOUT_S = 120.0
+
+
+# A step dispatcher: given a CompositeStep, start its atomic operation and return the
+# operation_id the supervisor will then watch. Injected so tests need no hub/drone.
+DispatchFn = Callable[[CompositeStep], Awaitable[str]]
+
+# A state reader: given an operation_id, return the reconciled atomic state as a
+# string ("pending" | "in_progress" | "completed" | "failed" | "interrupted" | ...),
+# or None if unknown. Reads the RECONCILED state — never the raw queue.
+ReadStateFn = Callable[[str], Optional[str]]
+
+# A guard check: inspect the live composite and return an abort reason string if a
+# guard fires, or None to continue. The guards themselves are the next piece; the
+# supervisor just calls this hook each tick. Injected; defaults to "no guards".
+GuardFn = Callable[[CompositeOperation], Optional[str]]
+
+
+# Atomic states that count as a positive, successful completion of a step.
+_POSITIVE_TERMINAL = {"completed"}
+# Atomic states that mean the step ended without success → the composite cannot
+# simply advance; it must react (abort / return home).
+_NEGATIVE_TERMINAL = {"failed", "rejected", "cancelled", "interrupted"}
+
+
+@dataclass
+class SupervisorConfig:
+    poll_interval_s: float = _DEFAULT_POLL_INTERVAL_S
+    step_timeout_s: float = _DEFAULT_STEP_TIMEOUT_S
+
+
+class OperationSupervisor:
+    """Drives one CompositeOperation through its steps in a closed loop.
+
+    The supervisor owns the composite's mission-level progression. For each step it:
+      1. transitions the composite to the right mission state (in_transit / returning),
+      2. dispatches the step's atomic action (injected DispatchFn) and records the
+         resulting operation_id on the step,
+      3. polls the reconciled atomic state at the configured cadence until it reaches
+         a terminal state — advancing on a positive one, aborting on a negative one,
+      4. on every tick, runs the guard hook; if a guard fires, it aborts (the safe
+         default is to stop and let the caller route to return-home).
+
+    It never drains the telemetry queue and never reaches into the atom's state
+    machine — it reads reconciled state and advances its OWN (composite) machine.
+    """
+
+    def __init__(self, dispatch: DispatchFn, read_state: ReadStateFn,
+                 guard: Optional[GuardFn] = None,
+                 config: Optional[SupervisorConfig] = None,
+                 sleep: Optional[Callable[[float], Awaitable[None]]] = None,
+                 now: Optional[Callable[[], float]] = None):
+        self._dispatch = dispatch
+        self._read_state = read_state
+        self._guard = guard or (lambda comp: None)
+        self._config = config or SupervisorConfig()
+        # Injected clock/sleep so tests run instantly and deterministically.
+        if sleep is None:
+            import asyncio
+            sleep = asyncio.sleep
+        self._sleep = sleep
+        if now is None:
+            import time
+            now = time.monotonic
+        self._now = now
+
+    async def run(self, comp: CompositeOperation) -> CompositeState:
+        """Drive the composite to a terminal mission state and return it.
+
+        Returns COMPLETED if every step reached a positive terminal state, or
+        ABORTED/FAILED if a guard fired, a step failed, or a step stalled.
+        """
+        if comp.state != CompositeState.PLANNING:
+            raise ValueError(
+                f"supervisor expects a freshly composed operation in PLANNING, "
+                f"got {comp.state.value}")
+
+        comp.transition_to(CompositeState.IN_TRANSIT, reason="supervisor started")
+
+        while True:
+            step = comp.current_step
+            if step is None:
+                # All steps consumed without a dedicated return step having moved us to
+                # RETURNING — treat the sequence as done.
+                break
+
+            # The return step flips the mission into RETURNING (its own leg).
+            if step.kind == "return" and comp.state == CompositeState.IN_TRANSIT:
+                comp.transition_to(CompositeState.RETURNING, reason="returning to base")
+
+            # Guard check BEFORE dispatching the next step — never start a step if a
+            # guard already says stop.
+            reason = self._guard(comp)
+            if reason is not None:
+                return self._abort(comp, f"guard: {reason}")
+
+            # Dispatch the step's atomic action; record the operation_id to watch.
+            try:
+                operation_id = await self._dispatch(step)
+            except Exception as e:
+                return self._abort(comp, f"dispatch raised: {e}")
+            step.operation_id = operation_id
+
+            outcome = await self._await_step(comp, operation_id)
+            if outcome == "positive":
+                comp.advance()
+                continue
+            if outcome == "guard":
+                # _await_step already knows the reason via the guard; abort generically.
+                return self._abort(comp, "guard fired during step")
+            if outcome == "stalled":
+                return self._abort(comp, f"step '{step.action}' stalled (no positive signal)")
+            # negative terminal
+            return self._abort(comp, f"step '{step.action}' ended in a non-success state")
+
+        # Every step done. If we were returning, we are home; otherwise close directly.
+        if comp.state == CompositeState.RETURNING:
+            comp.transition_to(CompositeState.COMPLETED, reason="returned to base")
+        else:
+            # No explicit return step; still a successful completion of all steps.
+            comp.transition_to(CompositeState.RETURNING, reason="no explicit return step")
+            comp.transition_to(CompositeState.COMPLETED, reason="all steps completed")
+        return comp.state
+
+    async def _await_step(self, comp: CompositeOperation, operation_id: str) -> str:
+        """Poll the reconciled atomic state until terminal. Returns one of:
+        'positive' | 'negative' | 'guard' | 'stalled'. Runs the guard hook each tick —
+        the closed loop: every sample, decide."""
+        started = self._now()
+        while True:
+            # Guard check every tick — real-time reaction, not only at waypoints.
+            reason = self._guard(comp)
+            if reason is not None:
+                log.info("supervisor: guard fired mid-step on %s: %s",
+                         comp.composite_id, reason)
+                return "guard"
+
+            state = self._read_state(operation_id)
+            if state in _POSITIVE_TERMINAL:
+                return "positive"
+            if state in _NEGATIVE_TERMINAL:
+                return "negative"
+
+            # Backstop: a step that never reaches terminal must not hang forever.
+            if self._now() - started > self._config.step_timeout_s:
+                return "stalled"
+
+            await self._sleep(self._config.poll_interval_s)
+
+    def _abort(self, comp: CompositeOperation, reason: str) -> CompositeState:
+        """Move the composite to ABORTED (safe default). The caller is responsible for
+        routing the vehicle home — the supervisor records the decision; the return
+        itself is a separate dispatched action the caller may issue."""
+        if not comp.is_terminal:
+            comp.transition_to(CompositeState.ABORTED, reason=reason)
+        log.warning("supervisor: composite %s aborted — %s", comp.composite_id, reason)
+        return comp.state