DHCP SIMULATOR GOVERNING ROADMAP
Version 2.9.0-sim — Validation and Reproducibility Foundation

1. MISSION AND NON-OPERATIONAL BOUNDARY

DHCP is an isolated educational, research, software-engineering, and supervised
training-concept simulator for a modern drone-port hub. Its modeled fleet is
ALL-UNMANNED cargo drone/UAS: no manned aircraft and no onboard pilots, crew,
or passengers. It MUST NOT connect to, authorize, navigate, or command a live
aircraft. Its maps, tracks, telemetry, airworthiness records, releases,
approvals, and scores MUST remain visibly marked as simulated and
non-operational.

The objective is a credible connected model of drone-port work: decisions,
dependencies, consequences, recovery, and review. It is not a generic flight
game and it is not a substitute for an approved aircraft model, certified
training device, operational safety case, regulator approval, or site study.

Every release MUST:

1. strengthen drone-port process fidelity and domain invariants;
2. preserve deterministic, reproducible, single-authority state transitions;
3. improve professional operator and instructor usability;
4. add verification proportional to the failure risk;
5. measure performance and bound high-rate or long-running data;
6. preserve the simulation-only technical boundary; and
7. update this roadmap, changelog, version metadata, and engineering evidence.

2. AUTHORITATIVE SHARED OPERATIONAL MODEL

All workspaces and services consume one SimulationSession. Unmanned cargo UAS,
missions, cargo, batteries, personnel, facilities, pads, maintenance, traffic,
weather, alarms, analytics, mapping, scenarios, replay, persistence, and
training assessment refer to the same exercise state. Internal domain/type
names such as `Aircraft` are neutral compatibility names and MUST NOT be
presented as evidence of a manned vehicle model.

The simulation authority is the only writer. UI pages, telemetry laboratories,
heavy-transport views, monitoring audio, analytics, maps, planners, persistence
exports, and AI recommendations are observers. They receive detached snapshots
or isolated payloads and MUST NOT mutate simulation truth or bypass cargo,
dispatch, maintenance, pad, airspace, reserve, authorization, or recovery
gates.

3. CONNECTED DRONE-PORT LIFECYCLE

DHCP SHALL model this connected flow:

Mission demand -> cargo acceptance -> custody inspection -> sorting/staging ->
dispatch planning -> UAS selection -> maintenance/airworthiness check ->
battery allocation -> pad reservation -> personnel and obstruction clearance ->
launch release -> route/traffic execution -> delivery -> return/recovery ->
post-flight inspection -> payload handling -> battery service -> corrective
maintenance -> cleaning/configuration -> next cargo load -> pad staging ->
release readiness.

Constraints MUST propagate. Closed pads reduce throughput; unavailable qualified
staff block work; non-dispatchable batteries block release; unresolved findings
ground aircraft; cargo holds prevent loading; weather and airspace constraints
affect sequencing and recovery; payload class/capacity constrains assignment;
acknowledgement never resolves an active hazard; and monitoring audio never
changes alarm lifecycle or command authority.

4. HUB SIMULATION-MODEL SCOPE

Drone Hub Alpha includes:

- Operations Center;
- cargo receiving, inspection, sorting, storage, and staging;
- launch and recovery pads;
- maintenance hangar and inspection positions;
- battery vault, cooling/quarantine positions, and charging bank;
- Weather Station and RF Tower;
- Emergency Landing Zone; and
- personnel, shifts, certifications, workload, queues, facility health,
  occupancy, capacity, and current work.

5. PERSISTENCE AND EVENT INTEGRITY

Persistence remains separate from simulation control.

The default educational deployment uses Python sqlite3/SQLite with explicit
transactions, foreign-key enforcement, WAL mode, versioned schema metadata,
integrity verification, retry for bounded transient lock contention, and a
private connection per worker.

Schema version 12 persists the current 52-row model-configuration evidence
catalog, the current replay identity, and compact detached checkpoint replay
identities. Evidence storage remains read-only with respect to the exercise and
cannot become a second writer.

The audit journal is append-only and hash chained. Restart recovery MUST verify
the existing chain before appending. Tick rollback MUST also roll the journal
back to the pre-tick checkpoint so a failed transaction cannot leave false
audit evidence.

Future SQLAlchemy, Alembic, PostgreSQL, and PostGIS implementations MUST preserve
the same repository boundary and domain invariants. Redis may only hold
disposable cache/coordination data. Durable event distribution may be explored,
but no external bus becomes aircraft or exercise authority.

6. USER EXPERIENCE AND TRAINING STANDARD

The PyQt6 console MUST keep simulation status, elapsed time, run state, alarms,
and operational posture legible while navigating. Workspaces MUST share UAS
focus and consume snapshots rather than query SQLite. Hidden pages MUST not
perform high-cost refreshes. Tables that present operational truth are
read-only. Severity is paired with text/icon cues, keyboard focus is visible,
and destructive exercise controls are clearly separated and confirmed. Map
shape identifies educational UAS class while color identifies operational
phase. Monitoring audio is optional and fail-silent; visual state remains
authoritative.

Training scenarios MUST identify learning objectives, starting conditions,
expected decisions, injected events, instructor observations, completion
criteria, and after-action evidence. Automated scores support instructor
judgment; they do not independently certify competence.

7. COMPLETED FOUNDATION

Delivered through v2.5.0-sim:

- typed, leased, authorized, sequenced, safety-evaluated, and audited simulated
  commands;
- one shared hub model spanning cargo, fleet, energy, personnel, facilities,
  maintenance, dispatch, airspace, recovery, turnaround, analytics, resilience,
  scenarios, replay, and SQLite persistence;
- cargo custody and turnaround state machines;
- maintenance findings, work orders, parts, airworthiness release, reliability,
  and readiness projections;
- delivery-site limits, strategic operation intents, route/corridor planning,
  conflict prediction, launch/recovery sequencing, and service capacity;
- post-flight inspection, incident, diversion, and return-to-service records;
- bounded telemetry and operational measurements;
- explicit UI ownership for every top-level snapshot dataset;
- role-aware, keyboard-oriented workspaces with shared aircraft focus, custom
  iconography, and simulation/non-navigation labeling.

Completed in v2.6.0-sim — Runtime Reliability Foundation:

- single-writer guard and transactional tick rollback;
- observer and snapshot-subscriber exception isolation;
- bounded I/O and CPU worker lanes with backpressure;
- asynchronous SQLite persistence;
- runtime incident, health, timing, and degraded-mode visibility.

Completed in v2.7.0-sim — Phase 27, Full-Sweep Integrity and Readiness:

- route-distance/speed-based aircraft motion with timestep-invariant progress,
  position, energy, and explicit motion time;
- finite-value, telemetry, target, reserve, and domain safety hardening;
- atomic command pairing and retry-safe sequence handling;
- detached pure snapshots plus complete rollback, reset, and replay state;
- stricter cargo/dispatch/recovery/turnaround/maintenance invariants;
- distinct alarm acknowledgement and hazard resolution;
- bounded operational histories and visibility-aware subscriber delivery;
- dedicated bounded simulation command-thread execution with GUI-thread
  snapshot dispatch;
- worker heartbeat/restart supervision, journal restart recovery, and database
  retry/version diagnostics;
- repaired console launch path, read-only presentation tables, meaningful
  trends, transparent icons, and accessible focus/danger states;
- reproducible package versioning and a full engineering acceptance matrix.

Completed in v2.8.0-sim — Phase 28, Mixed-Class Unmanned Cargo Extension:

- all-unmanned `PARCEL`, `LARGE`, `HEAVY`, and `EXTRA_HEAVY` educational
  cargo-UAS classes with no onboard pilot, crew, passenger, or manned-aircraft
  model;
- transparent non-certified performance references and payload-class
  compatibility in the shared deterministic session;
- pure bounded Heavy Transport telemetry for payload/mass, energy/power,
  endurance, wind, C2 link, altitude, speed, freshness, and status;
- a dedicated Heavy Transport Operations workspace with generic generated
  class imagery and explicit model/control boundaries;
- class-specific map shapes/codes, operational-phase colors, emergency override,
  and context-aware selected-UAS telemetry;
- semantic alarm audio with silent baseline, new warning/critical and resolved
  cues, priority, deduplication, cooldown, replay suppression, mute/volume,
  bounded state, and fail-silent asynchronous Qt playback;
- no control-authority coupling from heavy-transport observers, mapping,
  generated imagery, context views, or monitoring audio;
- primary-source attribution treating 30 kg, 100 kg, and 350 kg as industry
  payload-scale reference points only—not profile validation, vendor twins, or
  legal/certification categories.

Implemented in the v2.9.0-sim candidate — Phase 29 foundation, exit gate open:

- 52 immutable parameter-evidence records across the four educational classes,
  with units, local source/date, derivation, uncertainty, validity range,
  status, schema, model version, and configuration identity;
- model configuration identity
  `de52a82a31642cd8bd6ba4176b05603c76958c0a1426c01582aa64088841862d`;
- 20 pinned vendor-independent deterministic reference scenarios and a
  packaged 972-case sensitivity corpus with no runtime network dependency;
- all evidence explicitly `ESTIMATED` and all parameters
  `NOT_CALIBRATED`; no accepted empirical calibration dataset;
- session-integrated climb, cruise, descent, hover/dwell, return, approach,
  go-around, hold, alternate, and complete phases with bounded progress,
  distance, altitude, energy, and time;
- fail-closed phase-input authority defaults; separate hub and alternate-site
  simulation-only landing authorization; projected post-descent battery
  checked against the profile reserve; and visible projected reserve margin;
- hub recovery gated on a non-alternate grounded `COMPLETE` detailed state,
  while alternate-site completion creates no hub-pad or turnaround handoff;
- corrected default one-way mixed-fleet reference routes of 1.5 km (`LARGE`),
  1.2 km (`HEAVY`), and 4.0 km (`EXTRA_HEAVY`) after complete
  climb/dwell/return/reserve accounting, explicitly as local fixtures rather
  than calibrated range claims;
- incrementally maintained replay hashes tied to release, seed, normalized
  bounded input history/prefix identity, model configuration, canonical state,
  and numerical tolerances, including work-order inputs and personnel/airspace
  state;
- detached checkpoint returns with pre-restore state-hash verification, plus
  reset-generation invalidation of stale asynchronous persistence callbacks;
- SQLite schema 12 normalized model/replay evidence from detached session and
  checkpoint payloads; and
- repaired generic `LARGE` presentation artwork with the missing propulsion-pod
  structural support restored.

Phase 29 is not complete merely because this implementation exists. The exact
536-test suite, non-Qt package/install smoke, and 30-minute 50-UAS
core/authority fault-injected soak are recorded for v2.9. Outer-archive
handoff, cross-platform replay, supported-host Qt/EGL interaction, real
audio-device evidence, empirical calibration, and independent validation
remain external or open.

8. PERMANENT RELEASE GATES

A release is not complete until the applicable evidence is recorded:

- unit, integration, property, rollback, persistence, and source-contract tests;
- deterministic replay and large-step/small-step equivalence within stated
  numerical tolerances;
- invalid/non-finite input, stale telemetry, duplicate command, partial failure,
  and restart recovery tests;
- Qt offscreen launch/navigation/interaction smoke tests on a host with the
  required Qt system libraries;
- 50-aircraft minimum soak with injected observer, persistence, and worker
  faults, bounded queues/histories, stable memory after warm-up, and no GUI
  thread simulation work;
- wheel/sdist build, install smoke, version consistency, and archive hygiene;
- mixed-class profile/taxonomy, payload compatibility, map-shape/phase-color,
  context telemetry, Heavy Transport workspace, and monitoring-audio lifecycle,
  replay, bounded-memory, and fail-silent tests;
- instructor review of scenario objectives and after-action evidence;
- updated limits and deferred-risk statements.

9. ORDERED FORWARD ROADMAP

Phase 29 — Validation, calibration, and reproducibility

Status: implementation foundation present; exit gate remains open.

Implemented in the candidate:

- versioned parameter provenance, units, configuration, uncertainty, validity
  range, evidence status, and stable configuration identity;
- vendor-independent local reference scenarios;
- ten explicit session flight phases including go-around, hold, and alternate;
- profile-reserve landing authorization and locally feasible default
  mixed-fleet reference routes, without treating those fixtures as calibration;
- bounded sensitivity analysis across payload, wind, temperature, reserve, and
  selected phase factors;
- deterministic replay identity from version, seed, normalized inputs, model
  configuration, and state; and
- timestep/class/route/non-finite behavioral and property coverage.

Still required:

- accept and document configuration-specific empirical datasets;
- calibrate against those datasets and publish actual residuals rather than
  estimated error budgets;
- validate on data separate from the calibration partition;
- reproduce replay hashes or documented tolerances across supported platforms;
- complete exact-package suite/build/install/archive evidence;
- complete the required long soak and supported-host Qt/audio-device gates.

Exit gate: reference scenarios reproduce within declared error/uncertainty
bands; model claims never exceed their validation evidence; replay hashes match
across supported platforms or documented numerical tolerances.

Phase 30 — Vertiport layout and class-specific pad compatibility

- model pad dimensions, rotor/wing envelope, stand/taxi/approach geometry,
  obstacle clearance, downwash/outwash, surface loading, and safety zones;
- distinguish multirotor, lift-plus-cruise, hybrid-VTOL, and fixed-wing/airfield
  ground requirements without introducing manned aircraft;
- add class-compatible staging, recovery, charging, loading, maintenance, and
  emergency positions with explicit occupancy/separation;
- integrate site layout with scheduling, capacity, weather, contingency, map,
  persistence, replay, and UI evidence.

Exit gate: an incompatible UAS cannot reserve, stage, launch, recover, or
turnaround on a pad/stand; geometry and separation assumptions are documented,
visible, deterministic, and testable.

Phase 31 — Cargo center of gravity, volume, hazards, and handling

- represent dimensions, volume, center-of-gravity envelope, floor loading,
  restraint points, sling/load dynamics, and handling-equipment compatibility;
- add dangerous-goods, temperature-control, contamination, security, and
  special-handling states as educational workflow concepts;
- model qualified loading teams, inspection independence, loading plans,
  custody evidence, hold reasons, and post-flight disposition;
- propagate cargo constraints through profile selection, pad choice, dispatch,
  energy, performance, incident, and training assessment.

Exit gate: weight alone can never establish loadability; every accepted load has
class/profile compatibility, dimensional/CG/restraint/hazard evidence, audited
custody, and replay-visible handling decisions.

Phase 32 — Battery thermal behavior and degradation

- replace fixed capacity assumptions with documented chemistry/configuration,
  temperature, state-of-charge, state-of-health, power, and cycle effects;
- model charge/discharge curves, thermal limits, cooling, quarantine,
  charger/connector compatibility, exchange logistics, and degradation;
- propagate thermal or health limits into power/endurance estimates,
  dispatch/recovery reserve, maintenance, alarms, and hub capacity;
- validate long-duration numerical stability and bounded history/telemetry.

Exit gate: no UAS dispatch or recovery estimate treats percentage alone as
available energy; thermal, health, power, reserve, and class compatibility are
explicit and tested.

Phase 33 — Weather, terrain, obstacle, noise, and contingency depth

- model spatial/temporal wind fields, gusts, precipitation, temperature, icing
  concepts, visibility, and class-specific sensitivity with uncertainty;
- add terrain/elevation, obstacle clearance, route/alternate feasibility, and
  emergency/contingent landing-site compatibility;
- model missed approach, go-around, hold, diversion, corridor closure,
  communications/navigation uncertainty, and recovery resequencing;
- add downwash/noise/community-window exposure and explainable hub/route impact;
- integrate the provider-neutral map with an active MapLibre Qt WebEngine
  surface only after offline/provider/outage, performance, accessibility, and
  “NOT FOR NAVIGATION” gates pass.

Exit gate: weather/terrain/noise values have provenance and validity ranges; no
contingency teleports a UAS or bypasses timing, reserve, authorization,
compatible-site, or post-event inspection gates.

Phase 34 — Instructor console and validated training assessment

- package objectives, prerequisites, expected decisions, inject schedule,
  branching conditions, class-specific cues, and completion criteria;
- separate instructor controls from operator command surfaces;
- add bookmarks, annotations, synchronized replay, decision provenance, and
  structured after-action reports including monitoring-audio state;
- validate scoring rubrics with qualified subject-matter experts and prevent
  acknowledgement, muting, page navigation, or replay from gaming outcomes;
- conduct accessibility and human-factors trials with representative ground
  roles, alarm loads, mixed-class operations, and degraded audio.

Exit gate: every training package passes instructor/SME review and reconstructs
all material decisions; the score is explainable from authoritative events and
cannot depend on presentation-only state.

Phase 35 — Scale, release assurance, and optional laboratory services

- profile 50, 100, and 250-UAS mixed fleets and eliminate superlinear hot paths
  where operationally meaningful;
- run long-duration memory, audio-storm, queue, SQLite contention, restart, and
  injected-fault soaks;
- maintain screenshot baselines at 1080p/4K, keyboard-only navigation,
  screen-reader naming, reduced motion, and color/shape-independent state;
- produce reproducible builds, dependency/archive checks, release provenance,
  install smoke, and supported-platform matrices;
- optionally stabilize a repository interface, SQLAlchemy/Alembic migrations,
  PostgreSQL/PostGIS, tenancy, backup/restore, and observer replicas while
  preserving one exercise authority.

Exit gate: published performance/accessibility evidence meets named budgets on
named reference hardware; optional services produce equivalent domain results
and cannot introduce a live-UAS integration or second authority.
