dhcp-simulator 2.9.0__py3-none-any.whl

dhcp/__init__.py

@@ -0,0 +1,2 @@
+"""Drone Hub Control Port educational simulator."""
+__version__ = "2.9.0-sim"

dhcp/ai_operations/contracts.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from uuid import UUID, uuid4
+
+
+@dataclass(frozen=True, slots=True)
+class AIRecommendation:
+    mission_id: UUID
+    action: str
+    confidence: float
+    evidence_refs: tuple[str, ...]
+    limitations: tuple[str, ...]
+    expires_at: datetime
+    requires_human_approval: bool = True
+    recommendation_id: UUID = field(default_factory=uuid4)
+
+    def __post_init__(self) -> None:
+        if not 0 <= self.confidence <= 1:
+            raise ValueError("confidence must be between 0 and 1")

dhcp/apps/operations_console.py

@@ -0,0 +1,33 @@
+def main() -> None:
+    import sys
+    try:
+        from PyQt6.QtWidgets import QApplication
+    except ImportError as exc:
+        raise SystemExit("Install the optional UI dependency: pip install -e '.[ui]'") from exc
+    from dhcp.ui.main_window import OperationsMainWindow
+    from dhcp.ui.theme import APP_STYLESHEET
+    app = QApplication([])
+    app.setApplicationName("DHCP Simulator")
+    app.setStyleSheet(APP_STYLESHEET)
+    window = OperationsMainWindow()
+
+    def contain_uncaught_exception(exc_type, exc, traceback) -> None:
+        # Qt callback failures must never terminate the operations console.
+        window.session.containment.capture(
+            "application", "uncaught_exception", exc, window.session.elapsed_s, recovered=True
+        )
+        try:
+            window.session.request_command(
+                "pause_after_uncaught_ui_exception",
+                window.session.pause,
+            )
+        except Exception:
+            pass
+
+    sys.excepthook = contain_uncaught_exception
+    window.show()
+    app.exec()
+
+
+if __name__ == "__main__":
+    main()

dhcp/apps/simulation_console.py

@@ -0,0 +1,35 @@
+from dhcp.core.clock import ManualClock
+from dhcp.audit.journal import AppendOnlyJournal
+from dhcp.communications.lease import LeaseRegistry
+from dhcp.safety.kernel import SafetyKernel
+from dhcp.services.coordinator import CommandCoordinator
+from dhcp.domain.models import *
+from dhcp.domain.enums import *
+from dhcp.simulation.aircraft import SimulatedAircraft
+from dhcp.emergencies.engine import EmergencyEngine
+from dhcp.eta.engine import EtaEngine
+
+def command(a,m,op,kind,seq,clock):
+ return AuthorizedCommand(a.aircraft_id,m.mission_id,kind,op,1,seq,clock.now(),clock.now()+30)
+
+def main():
+ clock=ManualClock(100); journal=AppendOnlyJournal(); leases=LeaseRegistry(); safety=SafetyKernel()
+ coordinator=CommandCoordinator(clock,leases,safety,journal)
+ aircraft=Aircraft("SIM-101"); mission=Mission(aircraft.aircraft_id,1.2,3.0)
+ operator=OperatorContext("operator-1",frozenset({"dispatcher","pad_operator","flight_operator","emergency_operator"}))
+ leases.grant(ControlLease(aircraft.aircraft_id,operator.operator_id,1,clock.now(),clock.now()+3600))
+ seq=0
+ for kind in (CommandType.RESERVE,CommandType.BEGIN_PREFLIGHT,CommandType.AUTHORIZE_LAUNCH,CommandType.LAUNCH):
+  seq+=1; decision=coordinator.execute(aircraft,mission,command(aircraft,mission,operator,kind,seq,clock)); print(kind,decision.reason_code)
+ sim=SimulatedAircraft(aircraft,mission); emergency=EmergencyEngine(); eta=EtaEngine()
+ while mission.progress<0.92:
+  clock.advance(5); telemetry=sim.step(clock.now(),5); issue=emergency.evaluate(telemetry)
+  estimate=eta.estimate(mission.route_distance_km,mission.progress,max(telemetry.speed_mps,0.1))
+  print(f"progress={mission.progress:5.1%} battery={aircraft.battery_pct:5.1f}% ETA={estimate.seconds:5.0f}s")
+  if issue: print("EMERGENCY",issue.classification,issue.response); break
+ if not issue:
+  seq+=1; print(CommandType.AUTHORIZE_LANDING,coordinator.execute(aircraft,mission,command(aircraft,mission,operator,CommandType.AUTHORIZE_LANDING,seq,clock),telemetry).reason_code)
+  seq+=1; print(CommandType.LAND,coordinator.execute(aircraft,mission,command(aircraft,mission,operator,CommandType.LAND,seq,clock),telemetry).reason_code)
+ print("final",aircraft.state,mission.state,"audit_records",len(journal.records),"journal_valid",journal.verify())
+
+if __name__=='__main__': main()

dhcp/audit/journal.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from hashlib import sha256
+import json
+import os
+from pathlib import Path
+from tempfile import mkstemp
+from threading import Lock
+from types import MappingProxyType
+from typing import Any, Mapping
+from uuid import UUID
+
+from dhcp.domain.models import Event
+
+
+_ZERO_HASH = "0" * 64
+
+
+class JournalCorruptionError(RuntimeError):
+    """Raised when a complete journal record fails structural or hash validation."""
+
+    def __init__(self, path: Path, line_number: int, reason: str) -> None:
+        super().__init__(f"journal corruption at {path}, line {line_number}: {reason}")
+        self.path = path
+        self.line_number = line_number
+        self.reason = reason
+
+
+@dataclass(frozen=True, slots=True)
+class JournalRecoveryReport:
+    path: str | None
+    loaded_records: int
+    original_bytes: int
+    valid_bytes: int
+    truncated_bytes: int = 0
+    recovered_trailing_partial: bool = False
+    normalized_encoding: bool = False
+
+
+def _freeze_json(value: Any) -> Any:
+    if isinstance(value, dict):
+        return MappingProxyType({str(key): _freeze_json(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return tuple(_freeze_json(item) for item in value)
+    if isinstance(value, tuple):
+        return tuple(_freeze_json(item) for item in value)
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class StoredEvent:
+    """Immutable event representation retained by the audit chain."""
+
+    event_type: str
+    payload: Mapping[str, Any]
+    event_id: UUID | str
+    occurred_at: datetime
+    _canonical_text: str = field(repr=False)
+
+    def canonical(self) -> str:
+        return self._canonical_text
+
+
+def _stored_event(canonical_text: str) -> StoredEvent:
+    try:
+        raw = json.loads(canonical_text)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("event payload is not valid canonical JSON") from exc
+    if not isinstance(raw, dict):
+        raise ValueError("canonical event must be a JSON object")
+    required = {"event_id", "event_type", "occurred_at", "payload"}
+    if set(raw) != required:
+        raise ValueError("canonical event has unexpected fields")
+    if not isinstance(raw["event_type"], str) or not isinstance(raw["payload"], dict):
+        raise ValueError("canonical event types are invalid")
+    try:
+        occurred_at = datetime.fromisoformat(str(raw["occurred_at"]))
+    except ValueError as exc:
+        raise ValueError("canonical event timestamp is invalid") from exc
+    try:
+        event_id: UUID | str = UUID(str(raw["event_id"]))
+    except ValueError:
+        event_id = str(raw["event_id"])
+    return StoredEvent(
+        event_type=raw["event_type"],
+        payload=_freeze_json(raw["payload"]),
+        event_id=event_id,
+        occurred_at=occurred_at,
+        _canonical_text=canonical_text,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class JournalRecord:
+    index: int
+    previous_hash: str
+    record_hash: str
+    event: StoredEvent
+
+
+def _record_bytes(record: JournalRecord) -> bytes:
+    return (
+        f"{record.index}|{record.previous_hash}|{record.record_hash}|"
+        f"{record.event.canonical()}\n"
+    ).encode("utf-8")
+
+
+class AppendOnlyJournal:
+    """Thread-safe hash-chain journal with crash-safe restart and rollback support."""
+
+    def __init__(self, path: Path | str | None = None):
+        self._records: list[JournalRecord] = []
+        self._encoded_records: list[bytes] = []
+        self._lock = Lock()
+        self.path = Path(path) if path is not None else None
+        if self.path is not None:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self._recovery_report = self._load()
+        else:
+            self._recovery_report = JournalRecoveryReport(None, 0, 0, 0)
+
+    @property
+    def recovery_report(self) -> JournalRecoveryReport:
+        return self._recovery_report
+
+    def _parse_record(
+        self,
+        content: bytes,
+        *,
+        line_number: int,
+        expected_index: int,
+        previous_hash: str,
+    ) -> JournalRecord:
+        try:
+            line = content.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise ValueError("record is not valid UTF-8") from exc
+        parts = line.split("|", 3)
+        if len(parts) != 4:
+            raise ValueError("record does not contain four fields")
+        raw_index, stored_previous, stored_hash, canonical_text = parts
+        try:
+            index = int(raw_index)
+        except ValueError as exc:
+            raise ValueError("record index is not an integer") from exc
+        if index != expected_index:
+            raise ValueError(f"expected index {expected_index}, found {index}")
+        if stored_previous != previous_hash:
+            raise ValueError("previous hash does not match the chain")
+        if len(stored_hash) != 64:
+            raise ValueError("record hash has invalid length")
+        try:
+            int(stored_hash, 16)
+        except ValueError as exc:
+            raise ValueError("record hash is not hexadecimal") from exc
+        expected_hash = sha256((stored_previous + canonical_text).encode("utf-8")).hexdigest()
+        if stored_hash != expected_hash:
+            raise ValueError("record hash verification failed")
+        event = _stored_event(canonical_text)
+        return JournalRecord(index, stored_previous, stored_hash, event)
+
+    def _load(self) -> JournalRecoveryReport:
+        assert self.path is not None
+        if not self.path.exists():
+            self.path.touch()
+        raw = self.path.read_bytes()
+        original_size = len(raw)
+        physical_lines = raw.splitlines(keepends=True)
+        valid_source_bytes = 0
+        recovered_partial = False
+        previous = _ZERO_HASH
+        for position, physical_line in enumerate(physical_lines):
+            complete = physical_line.endswith(b"\n")
+            content = physical_line.rstrip(b"\r\n")
+            line_number = position + 1
+            try:
+                record = self._parse_record(
+                    content,
+                    line_number=line_number,
+                    expected_index=len(self._records),
+                    previous_hash=previous,
+                )
+            except ValueError as exc:
+                is_last_incomplete = position == len(physical_lines) - 1 and not complete
+                if not is_last_incomplete:
+                    raise JournalCorruptionError(self.path, line_number, str(exc)) from exc
+                recovered_partial = True
+                break
+            self._records.append(record)
+            encoded = _record_bytes(record)
+            self._encoded_records.append(encoded)
+            previous = record.record_hash
+            valid_source_bytes += len(physical_line)
+
+        normalized = b"".join(self._encoded_records)
+        normalized_encoding = raw[:valid_source_bytes] != normalized
+        truncated_bytes = original_size - valid_source_bytes if recovered_partial else 0
+        if recovered_partial or normalized_encoding or raw != normalized:
+            self._replace_file_locked(normalized)
+        return JournalRecoveryReport(
+            path=str(self.path),
+            loaded_records=len(self._records),
+            original_bytes=original_size,
+            valid_bytes=len(normalized),
+            truncated_bytes=max(0, truncated_bytes),
+            recovered_trailing_partial=recovered_partial,
+            normalized_encoding=normalized_encoding,
+        )
+
+    def _fsync_directory(self) -> None:
+        assert self.path is not None
+        try:
+            descriptor = os.open(self.path.parent, os.O_RDONLY)
+        except OSError:
+            return
+        try:
+            os.fsync(descriptor)
+        except OSError:
+            pass
+        finally:
+            os.close(descriptor)
+
+    def _replace_file_locked(self, content: bytes) -> None:
+        assert self.path is not None
+        descriptor, temporary_name = mkstemp(
+            prefix=f".{self.path.name}.",
+            suffix=".tmp",
+            dir=self.path.parent,
+        )
+        temporary = Path(temporary_name)
+        try:
+            with os.fdopen(descriptor, "wb") as handle:
+                handle.write(content)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, self.path)
+            self._fsync_directory()
+        finally:
+            if temporary.exists():
+                temporary.unlink()
+
+    def append(self, event: Event) -> JournalRecord:
+        canonical_text = event.canonical()
+        stored = _stored_event(canonical_text)
+        with self._lock:
+            previous = self._records[-1].record_hash if self._records else _ZERO_HASH
+            digest = sha256((previous + canonical_text).encode("utf-8")).hexdigest()
+            record = JournalRecord(len(self._records), previous, digest, stored)
+            encoded = _record_bytes(record)
+            if self.path is not None:
+                original_size = self.path.stat().st_size if self.path.exists() else 0
+                try:
+                    with self.path.open("ab") as handle:
+                        written = handle.write(encoded)
+                        if written != len(encoded):
+                            raise OSError("short audit-journal write")
+                        handle.flush()
+                        os.fsync(handle.fileno())
+                except BaseException:
+                    try:
+                        with self.path.open("r+b") as handle:
+                            handle.truncate(original_size)
+                            handle.flush()
+                            os.fsync(handle.fileno())
+                    except OSError:
+                        pass
+                    raise
+            self._records.append(record)
+            self._encoded_records.append(encoded)
+            return record
+
+    def checkpoint(self) -> int:
+        """Return a rollback marker representing the current record count."""
+        with self._lock:
+            return len(self._records)
+
+    def rollback(self, checkpoint: int) -> None:
+        """Atomically restore the chain to a prior ``checkpoint()`` marker."""
+        if not isinstance(checkpoint, int):
+            raise TypeError("checkpoint must be an integer record count")
+        with self._lock:
+            if checkpoint < 0 or checkpoint > len(self._records):
+                raise ValueError("checkpoint is outside the current journal")
+            if checkpoint == len(self._records):
+                return
+            retained_bytes = b"".join(self._encoded_records[:checkpoint])
+            if self.path is not None:
+                self._replace_file_locked(retained_bytes)
+            del self._records[checkpoint:]
+            del self._encoded_records[checkpoint:]
+
+    def verify(self) -> bool:
+        with self._lock:
+            previous = _ZERO_HASH
+            for expected_index, record in enumerate(self._records):
+                expected = sha256(
+                    (previous + record.event.canonical()).encode("utf-8")
+                ).hexdigest()
+                if (
+                    record.index != expected_index
+                    or record.previous_hash != previous
+                    or expected != record.record_hash
+                ):
+                    return False
+                previous = record.record_hash
+            return True
+
+    @property
+    def records(self) -> tuple[JournalRecord, ...]:
+        with self._lock:
+            return tuple(self._records)

dhcp/communications/lease.py

@@ -0,0 +1,10 @@
+from dhcp.domain.models import ControlLease
+class LeaseRegistry:
+    def __init__(self): self._leases={}
+    def grant(self,lease:ControlLease):
+        current=self._leases.get(lease.aircraft_id)
+        if current and lease.epoch<=current.epoch: raise ValueError("control epoch must increase")
+        self._leases[lease.aircraft_id]=lease
+    def validate(self,aircraft_id,owner,epoch,now):
+        lease=self._leases.get(aircraft_id)
+        return bool(lease and lease.owner==owner and lease.epoch==epoch and lease.active(now))

dhcp/communications/simulation_link.py

@@ -0,0 +1,9 @@
+from dhcp.domain.enums import OperationalMode
+class SimulationAircraftLink:
+    def __init__(self,mode=OperationalMode.SIMULATION):
+        if mode is not OperationalMode.SIMULATION: raise RuntimeError("simulation link cannot operate outside SIMULATION mode")
+        self.mode=mode; self.connected=False
+    async def connect(self): self.connected=True
+    async def submit_command(self,command):
+        if not self.connected: raise RuntimeError("link not connected")
+        return {"command_id":str(command.command_id),"acknowledged":True,"sequence":command.sequence_number}

dhcp/core/clock.py

@@ -0,0 +1,7 @@
+from time import monotonic
+class MonotonicClock:
+    def now(self)->float: return monotonic()
+class ManualClock:
+    def __init__(self,start:float=0.0): self.value=start
+    def now(self)->float: return self.value
+    def advance(self,seconds:float)->None: self.value+=seconds