dosync 0.4.1__py3-none-any.whl

dosync/policy_config.py

@@ -0,0 +1,252 @@
+"""
+DoSync — deployment policy configuration (POL-1).
+=================================================
+
+Device preferences are DEPLOYMENT configuration, not protocol and not reference-hub
+code (panel decision 2026-07-12, DoSync-Panel-Frontera-Deployment). The protocol
+defines HOW intent maps to capability; WHICH devices exist and WHAT preferences
+apply is the deployer's business — exactly as HTTP does not know which URLs live on
+your server.
+
+Until this module existed the principle was theory. `server.py` hard-coded one
+deployment's choices into the reference hub:
+
+    policy_engine.add(NeverAfterHoursPolicy(
+        actuator_types=["unlock", "alarm"],
+        blocked_hours_start=0, blocked_hours_end=6, ...))
+
+Who decided 00:00–06:00? One house. Every hub running this code inherited it, and
+changing it meant editing the reference implementation — which, as Sosa put it,
+means it was never configuration at all. Worse, policies that carry no deployment
+values but only make sense for some deployments (GeofencePolicy: "each deployment
+configures its own perimeter via the constructor", says its own docstring) could
+not be registered AT ALL without forking the hub.
+
+This module loads them from a file the deployer owns:
+
+    DOSYNC_POLICIES=/etc/dosync/policies.json  (or --policies)
+
+    {
+      "version": 1,
+      "policies": [
+        {"type": "never_after_hours",
+         "actuator_types": ["unlock", "alarm"],
+         "blocked_hours_start": 0, "blocked_hours_end": 6,
+         "reason": "No remote unlocking overnight"}
+      ]
+    }
+
+Being a file makes these shareable, forkable and versionable between deployments —
+the ecosystem of shared configurations the project wants to enable without having
+to curate it.
+
+FAIL LOUDLY, ON PURPOSE
+-----------------------
+Every error here raises. A policy is usually a RESTRICTION: "do not unlock at
+night", "confirm before the alarm", "never let the drone past this perimeter". A
+typo that silently skips one leaves the operator believing they are protected when
+they are not — strictly worse than refusing to start. So: unknown type, bad
+argument, missing file when one was configured — all raise. Silence is the failure
+mode this protocol has been paying for all along.
+
+Infrastructure policies (rate limits, conflict resolution, contextual weighting)
+are NOT loaded here: they carry no deployment values and are part of what the
+reference hub is. Only policies expressing a deployment's own choices live in this
+file.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .policies import (BasePolicy, BlockIntentPolicy, DeviceExclusionPolicy,
+                       GeofencePolicy, ManualControlActivePolicy,
+                       NeverAfterHoursPolicy, RequireConfirmationPolicy)
+
+if TYPE_CHECKING:
+    from .hub import DoSyncHub
+
+log = logging.getLogger("dosync.policy_config")
+
+CONFIG_VERSION = 1
+
+# type string -> (class, needs_hub)
+# Only deployment-expressing policies. Adding one here is the single step needed
+# to make it configurable; nothing else in the loader changes.
+POLICY_TYPES: dict[str, tuple[type[BasePolicy], bool]] = {
+    "never_after_hours":     (NeverAfterHoursPolicy,     False),
+    "require_confirmation":  (RequireConfirmationPolicy, False),
+    "device_exclusion":      (DeviceExclusionPolicy,     False),
+    "block_intent":          (BlockIntentPolicy,         False),
+    "geofence":              (GeofencePolicy,            False),
+    "manual_control_active": (ManualControlActivePolicy, True),
+}
+
+
+class PolicyConfigError(Exception):
+    """A deployment policy file could not be loaded. Never swallowed."""
+
+
+def _build_one(index: int, entry: dict, hub: "DoSyncHub | None") -> BasePolicy:
+    if not isinstance(entry, dict):
+        raise PolicyConfigError(f"policies[{index}]: expected an object, got {type(entry).__name__}")
+
+    ptype = entry.get("type")
+    if not ptype:
+        raise PolicyConfigError(f"policies[{index}]: missing required field 'type'")
+
+    if ptype not in POLICY_TYPES:
+        known = ", ".join(sorted(POLICY_TYPES))
+        raise PolicyConfigError(
+            f"policies[{index}]: unknown policy type {ptype!r}. Known types: {known}. "
+            "Refusing to start rather than silently skip a policy you asked for."
+        )
+
+    cls, needs_hub = POLICY_TYPES[ptype]
+    # Keys starting with "_" are metadata, not arguments. JSON has no comments,
+    # and a policy file MUST be documentable: a restriction whose reason nobody
+    # recorded is one nobody dares to remove later. "_why", "_owner", "_ticket"
+    # and friends are for humans and are ignored here.
+    kwargs = {k: v for k, v in entry.items()
+              if k != "type" and not k.startswith("_")}
+
+    if needs_hub:
+        if hub is None:
+            raise PolicyConfigError(
+                f"policies[{index}]: {ptype!r} needs the hub, but none was provided to the loader")
+        kwargs["hub"] = hub
+
+    try:
+        return cls(**kwargs)
+    except TypeError as e:
+        # Wrong/missing arguments: name the policy and the file position, because
+        # the raw TypeError ("__init__() got an unexpected keyword argument") does
+        # not tell an operator which entry of their file is wrong.
+        raise PolicyConfigError(f"policies[{index}] ({ptype}): {e}") from e
+
+
+def load_policies(path: str | Path, hub: "DoSyncHub | None" = None) -> list[BasePolicy]:
+    """Build the policy objects declared in a deployment policy file.
+
+    Raises PolicyConfigError on any problem — see the module docstring for why a
+    policy file must never fail quietly.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise PolicyConfigError(
+            f"policy file not found: {path}. A policy file was configured but does not "
+            "exist; refusing to start unprotected."
+        )
+
+    raw = path.read_text()
+    try:
+        doc = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise PolicyConfigError(f"{path}: invalid JSON — {e}") from e
+
+    # AUDIT-PROVENANCE (2026-07-18): fingerprint of the BYTES THAT WERE LOADED,
+    # computed here — at read time — and nowhere else. Hashing the file again
+    # later would fingerprint whatever is on disk THEN, which may not be what
+    # this hub is enforcing. The hash exists so an audit entry can answer
+    # "which exact policy file decided this?" months later, even if the file
+    # has since been edited.
+    global _last_loaded_fingerprint
+    _last_loaded_fingerprint = hashlib.sha256(raw.encode()).hexdigest()
+
+    if not isinstance(doc, dict):
+        raise PolicyConfigError(f"{path}: expected a JSON object at the top level")
+
+    version = doc.get("version")
+    if version != CONFIG_VERSION:
+        raise PolicyConfigError(
+            f"{path}: unsupported version {version!r} (this hub reads version {CONFIG_VERSION})")
+
+    # Top-level "_"-prefixed keys (e.g. "_README") are metadata too.
+    entries = doc.get("policies")
+    if entries is None:
+        raise PolicyConfigError(f"{path}: missing required field 'policies'")
+    if not isinstance(entries, list):
+        raise PolicyConfigError(f"{path}: 'policies' must be a list")
+
+    policies = [_build_one(i, entry, hub) for i, entry in enumerate(entries)]
+    log.info("Loaded %d deployment policy/policies from %s", len(policies), path)
+    return policies
+
+
+_last_loaded_fingerprint: str | None = None
+
+
+def load_into(engine, path: str | Path, hub: "DoSyncHub | None" = None) -> list[BasePolicy]:
+    """Load a policy file and register every policy on the engine.
+
+    Also stamps the engine with the SHA-256 of the loaded file
+    (engine.policies_fingerprint), so audit entries can bind decisions to the
+    exact configuration that made them.
+    """
+    policies = load_policies(path, hub=hub)
+    for p in policies:
+        engine.add(p)
+    engine.policies_fingerprint = _last_loaded_fingerprint
+    engine.policies_path = str(path)
+    return policies
+
+
+def lint_emergency_satisfiability(hub, policies: list) -> list[str]:
+    """Config-load lint (EMERGENCY-UNSAT part b): warn the operator the day they
+    write the rule, not the night of the fire.
+
+    Checks whether the DECLARED deployment policies, applied at EMERGENCY
+    urgency, would empty the plan for the canonical emergency intent
+    (ensure_safety) against the CURRENT registry. Returns human-readable
+    warnings; empty list means satisfiable (or nothing resolvable to begin
+    with — an empty registry is not the policies' fault).
+
+    Deliberately evaluates through a THROWAWAY engine containing only the
+    deployment policies: running a synthetic intent through the production
+    engine would consume rate-limit state just for linting.
+    """
+    from .models import Intent, IntentClass, Urgency
+    from .policies import PolicyDecision, PolicyEngine
+
+    warnings: list[str] = []
+    probe = PolicyEngine()
+    for pol in policies:
+        probe.add(pol)
+
+    intent = Intent(intent_id="lint-emergency-satisfiability",
+                    intent=IntentClass("ensure_safety"),
+                    urgency=Urgency.EMERGENCY, context={})
+    try:
+        plan = hub.resolver.resolve(intent)
+    except Exception as e:                         # lint must never block startup
+        log.warning("satisfiability lint skipped: resolver raised %s", e)
+        return warnings
+
+    pre = sorted({a.device_id for a in plan.actions})
+    if not pre:
+        return warnings                            # nothing to empty — not a policy problem
+
+    result = probe.evaluate(intent, plan)
+    if result and result.decision == PolicyDecision.MODIFY and not result.modified_actions:
+        warnings.append(
+            f"declared policies make EMERGENCY intent 'ensure_safety' UNSATISFIABLE for the "
+            f"current registry: {len(pre)} device(s) resolve, 0 survive policy filtering "
+            f"(deciding: {result.policy_name}). The rules will be honored — an emergency "
+            f"would execute nothing. If that is not what you meant, review the exclusions."
+        )
+    return warnings
+
+
+def configured_path() -> str | None:
+    """The deployment policy file, if this deployment configured one.
+
+    None means "this deployment declares no policies", which is a legitimate and
+    common state — not an error. The reference hub ships with NO deployment
+    policies, because the protocol has no opinion about your house.
+    """
+    return os.environ.get("DOSYNC_POLICIES") or None

dosync/reconciler.py

@@ -0,0 +1,177 @@
+"""
+DoSync — Operation reconciler (execution_model, Layer 3).
+========================================================
+
+Layer 1 defined the state machine. Layer 2 made operations survive a restart.
+This layer is the active component that *drives* an operation through its states
+based on what the device actually reports — telemetry.
+
+THE ONE RULE, from the panel: telemetry wins. The hub never assumes an operation
+succeeded; it advances only on a positive signal, and if telemetry contradicts the
+hub's model, the telemetry is right and the model is corrected. Silence is not
+success — a timeout or an absent signal never advances an operation to `completed`.
+
+DELIBERATELY HARDWARE-AGNOSTIC. The reconciler knows nothing about MAVLink, drones,
+ovens, or any protocol. It consumes ABSTRACT telemetry facts — a small vocabulary
+of `TelemetryEvent`s — and maps them to state transitions. The future MAVLinkAdapter
+is what translates real MAVLink messages into these abstract facts; the reconciler
+stays pure logic, fully testable by injecting fake telemetry. That separation is
+what lets the same reconciler serve a drone and an oven.
+
+The reconciler does NOT decide policy. It moves operations between states and
+records why. What to *do* about an operation that has been `paused_by_device` for
+too long (notify the operator, trigger RTL) is the Policy Engine's job — the
+reconciler only exposes the state and the time-in-state. (Panel: keep the model
+and the policy separate, or the model becomes unimplementable.)
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from dosync.operations import Operation, OperationState, InvalidTransition
+
+
+class TelemetryEvent(str, Enum):
+    """The abstract vocabulary of facts a device can report about a running
+    operation. An adapter translates device-native signals into these; the
+    reconciler maps these to state transitions. This list is intentionally small
+    and device-independent — a drone and an oven both speak it."""
+
+    # ── Progress facts (positive signals — the only way forward) ──────────────
+    STARTED = "started"                  # the action is confirmed underway
+    PREPARING = "preparing"              # a pre-action setup phase began (richer profile).
+                                         # Domain sub-phase (e.g. "arming") goes in the
+                                         # operation's `phase`, not in a new event name.
+    FINISHED = "finished"                # the action completed — positive completion signal.
+                                         # (A speaker finishes a track; a vehicle arrives.)
+
+    # ── Trouble facts ─────────────────────────────────────────────────────────
+    REJECTED_BY_DEVICE = "rejected_by_device"   # device refused (busy, not ready, unsafe)
+    FAILED = "failed"                    # failed partway through
+    DEVICE_PAUSED = "device_paused"      # the device paused itself (lost stream, storage full, wind)
+    DEVICE_RESUMED = "device_resumed"    # the device resumed on its own
+
+    # ── Human / control facts ─────────────────────────────────────────────────
+    MANUAL_CONTROL_TAKEN = "manual_control_taken"  # a human took manual control — interrupt
+    CANCELLED = "cancelled"              # explicit cancellation request honored
+
+
+# Maps a telemetry fact to the operation state it should drive toward. This is the
+# whole policy of "what does this fact mean for the lifecycle", in one table.
+# Note FINISHED → COMPLETED is the ONLY path to completion: there is no way to reach
+# COMPLETED without a positive FINISHED signal. Silence cannot complete an operation.
+_EVENT_TO_STATE: dict[TelemetryEvent, OperationState] = {
+    TelemetryEvent.STARTED:              OperationState.IN_PROGRESS,
+    TelemetryEvent.PREPARING:            OperationState.PREPARING,
+    TelemetryEvent.FINISHED:             OperationState.COMPLETED,
+    TelemetryEvent.REJECTED_BY_DEVICE:   OperationState.REJECTED,
+    TelemetryEvent.FAILED:               OperationState.FAILED,
+    TelemetryEvent.DEVICE_PAUSED:        OperationState.PAUSED_BY_DEVICE,
+    TelemetryEvent.DEVICE_RESUMED:       OperationState.IN_PROGRESS,
+    TelemetryEvent.MANUAL_CONTROL_TAKEN: OperationState.INTERRUPTED,
+    TelemetryEvent.CANCELLED:            OperationState.CANCELLED,
+}
+
+
+class ReconcileResult:
+    """The outcome of applying one telemetry fact to an operation. Carries enough
+    detail for the caller to persist the change and write an audit entry."""
+
+    __slots__ = ("operation", "changed", "from_state", "to_state", "note")
+
+    def __init__(self, operation: Operation, changed: bool,
+                 from_state: OperationState, to_state: OperationState, note: str = ""):
+        self.operation = operation
+        self.changed = changed
+        self.from_state = from_state
+        self.to_state = to_state
+        self.note = note
+
+    def __repr__(self) -> str:
+        if self.changed:
+            return (f"<Reconcile {self.operation.operation_id}: "
+                    f"{self.from_state.value} → {self.to_state.value}>")
+        return (f"<Reconcile {self.operation.operation_id}: no change "
+                f"({self.from_state.value}); {self.note}>")
+
+
+class OperationReconciler:
+    """Applies abstract telemetry facts to operations, advancing their state
+    machine. Pure logic — no I/O, no hardware. The hub feeds it telemetry (from an
+    adapter) and persists the result; the reconciler decides the state change.
+    """
+
+    def reconcile(self, operation: Operation, event: TelemetryEvent,
+                  reason: str = "", now: float | None = None) -> ReconcileResult:
+        """Apply one telemetry fact to one operation.
+
+        Returns a ReconcileResult describing whether the state changed. Telemetry
+        wins: if the fact maps to a legal transition, it is applied. If the fact is
+        irrelevant to the current state (e.g. a duplicate "started" while already
+        in progress), it is a no-op, not an error — telemetry can be noisy and
+        repeat. If the fact would require an illegal jump, that is surfaced as a
+        no-op with an explanatory note rather than crashing the hub: a late or
+        out-of-order telemetry packet must never take the hub down.
+        """
+        if isinstance(event, str):
+            event = TelemetryEvent(event)
+
+        from_state = operation.state
+        target = _EVENT_TO_STATE[event]
+
+        # Already there (idempotent telemetry) — common and harmless.
+        if from_state == target:
+            return ReconcileResult(operation, False, from_state, target,
+                                   note=f"already in {target.value}")
+
+        # Terminal operations never move — an interrupted op does not resume, a
+        # completed op stays completed even if a stale packet arrives later.
+        if operation.is_terminal:
+            return ReconcileResult(operation, False, from_state, from_state,
+                                   note=f"operation is terminal ({from_state.value}); "
+                                        f"telemetry '{event.value}' ignored")
+
+        # Apply if legal; otherwise no-op with a note. We do NOT force illegal
+        # transitions — but we also never silently pretend success.
+        if not operation.can_transition_to(target):
+            return ReconcileResult(operation, False, from_state, from_state,
+                                   note=f"telemetry '{event.value}' implies "
+                                        f"{target.value}, illegal from {from_state.value}")
+
+        full_reason = reason or f"telemetry: {event.value}"
+        try:
+            operation.transition_to(target, reason=full_reason, now=now)
+        except InvalidTransition as e:
+            # Defensive: can_transition_to said yes but transition raised. Surface
+            # as no-op rather than propagate — the hub must stay up.
+            return ReconcileResult(operation, False, from_state, from_state,
+                                   note=f"transition rejected: {e}")
+
+        return ReconcileResult(operation, True, from_state, target, note=full_reason)
+
+    def reconcile_after_restart(self, operation: Operation,
+                                now: float | None = None) -> ReconcileResult:
+        """Place a recovered operation into the transient RECONCILING state on hub
+        restart, so the hub re-confirms reality from telemetry before assuming the
+        operation is still where it left off. The failsafe may have acted while the
+        hub was down — the next real telemetry fact resolves it.
+
+        Only meaningful for telemetry-capable operations; a core-only device has no
+        telemetry to reconcile against, so it is left as-is.
+        """
+        from_state = operation.state
+        if not operation.telemetry_capable:
+            return ReconcileResult(operation, False, from_state, from_state,
+                                   note="core-only operation: nothing to reconcile")
+        if operation.is_terminal:
+            return ReconcileResult(operation, False, from_state, from_state,
+                                   note=f"terminal ({from_state.value}); no reconcile")
+        if not operation.can_transition_to(OperationState.RECONCILING):
+            return ReconcileResult(operation, False, from_state, from_state,
+                                   note=f"cannot reconcile from {from_state.value}")
+        operation.transition_to(OperationState.RECONCILING,
+                                reason="hub restart: reconciling against telemetry",
+                                now=now)
+        return ReconcileResult(operation, True, from_state, OperationState.RECONCILING,
+                               note="awaiting telemetry to resolve")

dosync/route_composer.py

@@ -0,0 +1,189 @@
+"""
+DoSync — Route composer (turns a composition intent into an ordered step sequence).
+===================================================================================
+
+The semantic resolver answers "which device and which capability for this intent?"
+— it does matching and returns a flat ActionPlan (parallel actions). A perimeter
+inspection is a different kind of problem: it is GEOMETRY (where are the waypoints
+around the center?) plus ORDER (take off, then each waypoint in sequence, then come
+home). That is route planning, not semantic matching.
+
+The expert panel placed this in a SEPARATE component (not a resolver subclass)
+because the BaseResolver contract is `resolve(intent) -> ActionPlan`, and an
+ActionPlan is FLAT — it cannot express "these steps run in order, each waiting for
+the previous to actually arrive." A route is a CompositeOperation, not an ActionPlan.
+So the composer lives here, and the hub routes a composition intent to it instead of
+to the flat resolver.
+
+GENERIC IN FORM, perimeter as the first concrete case. The composer produces an
+ordered list of CompositeStep. Today it knows one shape — a perimeter around a
+center — but the structure (takeoff → waypoints → return) generalizes to any spatial
+patrol. The navigation math (projecting waypoints around a center) lives here,
+visible and testable, not buried inside a semantic resolver.
+
+This module has NO drone dependencies and NO hub dependencies. It is pure geometry
+plus step construction, fully unit-testable on its own.
+
+DESIGN NOTE — who plans the route: the brain (AI) or the nervous system (DoSync)?
+This is a subtle but defining boundary, so it is worth stating explicitly.
+
+  The AI (the brain) decides the GOAL and its STRATEGIC PARAMETERS: *that* an area
+  should be inspected, the center, the radius, the altitude, the shape. None of that
+  is invented here — it all arrives as the intent and its context, authored by the
+  AI. This composer never decides whether to fly, where, or how high.
+
+  This composer (the nervous system / cerebellum) does only the DETERMINISTIC
+  TRANSLATION of that goal into exact motor geometry: given "perimeter, 1km, centered
+  here," there is exactly one correct set of corner coordinates. That is computation,
+  not decision — the same way the cerebellum turns "walk to the kitchen" into precise
+  joint kinematics without the conscious mind computing a single angle. That is why
+  compose_inspect_area RAISES if the center is missing: it refuses to invent a
+  decision that belongs to the brain.
+
+  Crucially, this composer is NOT mandatory. It is a translation SERVICE the AI uses
+  when it wants to delegate the geometry. An AI that prefers to plan every waypoint
+  itself — irregular paths, avoiding a zone, optimizing for wind — simply emits its
+  own go_to sequence directly and skips the composer entirely, exactly as a brain can
+  move a single limb deliberately instead of delegating the gait to the cerebellum.
+
+  In one line: the brain decides the goal and the parameters; the nervous system
+  translates that goal into exact motor geometry and keeps the loop closed during
+  execution. This file is translation, never autonomous planning.
+"""
+
+from __future__ import annotations
+
+import math
+
+from .composite_operations import CompositeStep
+
+
+# Mean Earth radius in meters (same constant used by the haversine helpers elsewhere,
+# kept local so this module depends on nothing).
+_EARTH_RADIUS_M = 6371000.0
+
+
+def destination_point(lat: float, lon: float, bearing_deg: float,
+                      distance_m: float) -> tuple[float, float]:
+    """Given a start point, a compass bearing, and a distance, return the
+    destination (lat, lon). This is the INVERSE of haversine (which measures the
+    distance between two known points); here we know one point, a direction, and a
+    distance, and we project the second point.
+
+    Standard great-circle (spherical) forward geodesic. Accurate to well within a
+    meter at the scales DoSync cares about (perimeters of a few km), and it has no
+    dependency on a projection library.
+
+    bearing_deg: 0 = North, 90 = East, 180 = South, 270 = West.
+    """
+    ang = distance_m / _EARTH_RADIUS_M          # angular distance in radians
+    brg = math.radians(bearing_deg)
+    p1 = math.radians(lat)
+    l1 = math.radians(lon)
+
+    p2 = math.asin(
+        math.sin(p1) * math.cos(ang)
+        + math.cos(p1) * math.sin(ang) * math.cos(brg)
+    )
+    l2 = l1 + math.atan2(
+        math.sin(brg) * math.sin(ang) * math.cos(p1),
+        math.cos(ang) - math.sin(p1) * math.sin(p2),
+    )
+    # Normalize longitude to [-180, 180].
+    lon2 = (math.degrees(l2) + 540) % 360 - 180
+    return (math.degrees(p2), lon2)
+
+
+def perimeter_waypoints(center_lat: float, center_lon: float,
+                        radius_m: float, sides: int = 4,
+                        start_bearing_deg: float = 0.0) -> list[tuple[float, float]]:
+    """Compute the vertices of a regular polygon (default: square) inscribed in a
+    circle of `radius_m` around the center. These are the corners the vehicle flies
+    to in order to patrol the perimeter.
+
+    sides=4 gives a square (the natural perimeter of a property); higher values
+    approximate a circular patrol. The vertices are returned in clockwise order
+    starting from `start_bearing_deg`.
+    """
+    if sides < 3:
+        raise ValueError("a perimeter needs at least 3 sides")
+    if radius_m <= 0:
+        raise ValueError("radius must be positive")
+    step = 360.0 / sides
+    return [
+        destination_point(center_lat, center_lon,
+                          (start_bearing_deg + i * step) % 360, radius_m)
+        for i in range(sides)
+    ]
+
+
+class RouteComposer:
+    """Composes an ordered CompositeStep sequence for a spatial composition intent.
+
+    Today it handles one intent shape — `inspect_area` — by building a perimeter
+    patrol around a center: take off, fly each perimeter vertex in order, return
+    home. The hub routes a composition intent here instead of to the flat resolver,
+    then wraps the returned steps in a CompositeOperation for the supervisor to drive.
+
+    Stateless and dependency-free: give it a device id and a context, get back steps.
+    """
+
+    # Sensible defaults; every value can be overridden via the intent context so a
+    # deployment configures its own patrol without code changes.
+    DEFAULT_RADIUS_M = 1000.0
+    DEFAULT_ALTITUDE_M = 30.0
+    DEFAULT_SIDES = 4
+
+    def compose_inspect_area(self, device_id: str, context: dict) -> list[CompositeStep]:
+        """Build the step sequence for an `inspect_area` intent.
+
+        Required context:
+          center: (lat, lon)  — the patrol center. The panel's design: this is the
+                                hub's own location (the system's "home"), so the
+                                perimeter is centered on where the coordinating mind
+                                physically sits.
+        Optional context:
+          radius_m, altitude_m, sides, start_bearing_deg — override the defaults.
+
+        Returns: take_off → go_to(each vertex) → return_home, as ordered CompositeSteps.
+        Raises ValueError if the center is missing — we never invent a location.
+        """
+        center = context.get("center")
+        if not center or len(center) != 2:
+            raise ValueError(
+                "inspect_area requires context['center'] = (lat, lon) — "
+                "the patrol center (the hub's location). We never invent a position."
+            )
+        center_lat, center_lon = float(center[0]), float(center[1])
+        radius_m = float(context.get("radius_m", self.DEFAULT_RADIUS_M))
+        altitude_m = float(context.get("altitude_m", self.DEFAULT_ALTITUDE_M))
+        sides = int(context.get("sides", self.DEFAULT_SIDES))
+        start_bearing = float(context.get("start_bearing_deg", 0.0))
+
+        vertices = perimeter_waypoints(center_lat, center_lon, radius_m,
+                                       sides=sides, start_bearing_deg=start_bearing)
+
+        steps: list[CompositeStep] = []
+
+        # 1. Take off to patrol altitude.
+        steps.append(CompositeStep(
+            device_id=device_id, action="take_off",
+            params={"alt": altitude_m}, kind="takeoff",
+        ))
+
+        # 2. Fly each perimeter vertex in order, at patrol altitude.
+        for i, (wlat, wlon) in enumerate(vertices):
+            steps.append(CompositeStep(
+                device_id=device_id, action="go_to",
+                params={"lat": wlat, "lon": wlon, "alt": altitude_m},
+                kind="waypoint",
+            ))
+
+        # 3. Return home and land. The panel: a patrol always ends back at base; the
+        #    return is part of the operation, not optional.
+        steps.append(CompositeStep(
+            device_id=device_id, action="return_home",
+            params={}, kind="return",
+        ))
+
+        return steps