also looking at this
feat: add shared-clock scoped vehicle simulation sessions
#98
42 files
+2764
-127
| @@ -0,0 +1,184 @@ | ||
| 1 | # Modeled cargo delivery | |
| 2 | ||
| 3 | The owned quadcopter runtime can execute a delivery mission with a carried point mass, | |
| 4 | captured release observations, receiver confirmation, a finite alternate landing and two | |
| 5 | modeled communication sources. The raw IMU/GNSS feed, estimator, controls, authority and | |
| 6 | independent output watchdog are the same paths used by the other owned vehicle profiles. | |
| 7 | ArduPilot and PX4 are optional drivers and are not used by this simulation. | |
| 8 | ||
| 9 | This is software simulation. Physical outputs remain inhibited and identity is not | |
| 10 | authenticated. A modeled receiver receipt does not establish a real recipient, hardware | |
| 11 | release, package condition, safe aircraft operation or authorization for BVLOS transport. | |
| 12 | ||
| 13 | ## Run a declared mission | |
| 14 | ||
| 15 | ```sh | |
| 16 | ./buddy cargo:mission examples/cargo-delivery.json | |
| 17 | ./buddy cargo:mission examples/cargo-delivery.json --scenario site-blocked | |
| 18 | ./buddy cargo:mission examples/cargo-delivery.json --scenario after-release-host-loss | |
| 19 | ``` | |
| 20 | ||
| 21 | The standalone `drone cargo:mission` command has the same arguments. The request file is | |
| 22 | required. It contains a complete `CargoDeliveryConfiguration`, as shown in the repository's | |
| 23 | [fictional example](https://github.com/stacksjs/drone/blob/main/examples/cargo-delivery.json). | |
| 24 | There is no inferred destination, parcel, alternate, power declaration or farm location. | |
| 25 | ||
| 26 | | Field | Declaration | | |
| 27 | |---|---| | |
| 28 | | `version`, `id` | Version `1` and an ASCII mission identifier, at most 40 characters | | |
| 29 | | `delivery.origin` | The synthetic feed's fixed WGS84 origin: latitude/longitude `0,0`, ellipsoid height `100` m | | |
| 30 | | `delivery.site` | Explicit site, recipient and container identifiers, `positionM` and capture radius | | |
| 31 | | `delivery.releaseHeightM` | Height above the receiver plane, from 0.3 to 3 m | | |
| 32 | | `load` | Point mass greater than zero and at most 0.25 kg; body-forward offset from -0.1 to 0.1 m | | |
| 33 | | `alternateM` | An explicit LOCAL_NED landing point on the modeled zero-down ground plane | | |
| 34 | | `power` | `availableWh`, conservative `maxW` and `reservePercent` | | |
| 35 | ||
| 36 | Down is positive. The receiver and alternate down coordinate must be zero. The carrier | |
| 37 | starts and returns at the local origin. Its modeled structural datum rests 0.1 m above | |
| 38 | the ground; qualified contact, rather than an invented exact zero position, completes | |
| 39 | landing. Sites and routes must fit the existing 12 m horizontal and -5 to 0 m down fence. | |
| 40 | This flat local world does not implement real terrain, arbitrary geodetic origins or | |
| 41 | long-range navigation. | |
| 42 | ||
| 43 | Site radius is 0.1 to 2 m. Site and recipient identifiers use lowercase ASCII letters, | |
| 44 | digits and hyphens, beginning with a letter, at most 64 characters; the container is | |
| 45 | limited to 40 characters by the carried-body model. Records reject extra fields, | |
| 46 | accessors and missing values. Tuples require three finite own data elements. | |
| 47 | ||
| 48 | The complete owned mission validator checks normal and alternate graph duration and | |
| 49 | reserve before a plant is allocated. The graph includes takeoff, destination, one | |
| 50 | material-drop request, return/landing, and a one-way alternate approach/landing after | |
| 51 | payload failure. No failure path retries release. Its fixed task deadlines give a worst | |
| 52 | case of 81,520 ms. The declared power ceiling must be at least 600 W; native mission | |
| 53 | capacity, reserve and power ceilings still apply. | |
| 54 | ||
| 55 | The example's 150 g parcel is 0.04 m aft of the structural datum. Its destination is | |
| 56 | `[2, 1, 0]`, release height 1.2 m, alternate `[-1, 1, 0]`, and budget 50 Wh/700 W/35% | |
| 57 | reserve. These are modeled declarations, not a recommended physical aircraft load. | |
| 58 | ||
| 59 | ## Outcomes and command delivery | |
| 60 | ||
| 61 | `cargo:mission` returns one compact JSON document, at most 16,384 UTF8 bytes including | |
| 62 | its final LF. It retains the admitted configuration, actual outcome, load, parcel, | |
| 63 | custody, link events, reserve budget and final board/authority observations. | |
| 64 | ||
| 65 | - Exit 0 requires a matched scenario, received custody and actual modeled carrier | |
| 66 | landing completion with neutral outputs. | |
| 67 | - Exit 2 retains a modeled diversion, blocked/incomplete mission, host loss or an | |
| 68 | unmatched scenario. Received custody can coexist with a later carrier failure. | |
| 69 | - Exit 1 covers invalid input, rejected admission, unavailable results and output | |
| 70 | failures. The handler attempts one fixed diagnostic without caller data. | |
| 71 | ||
| 72 | The request is a regular file bounded to 16,384 bytes, decoded with strict UTF8. A final | |
| 73 | symlink is refused; parent paths are followed. Reading is not path authorization or an | |
| 74 | atomic snapshot of concurrent file mutation. Accept results only after both streams | |
| 75 | reach EOF and the actual exit status is known. A failed output write can leave a prefix. | |
| 76 | JSON parsing uses native last-key-wins semantics. The CLI does not persist a full runtime | |
| 77 | journal, canonical signed request or authenticated output. | |
| 78 | ||
| 79 | The existing `cargo:deliver --scenario <name>` command remains a set of closed | |
| 80 | demonstrations with its original 100 g forward load. It exits 0 for matched fault | |
| 81 | demonstrations as well as the matched nominal route; it does not mean a parcel was | |
| 82 | delivered. Invalid input, unmatched demonstrations and output failures exit 1. | |
| 83 | The separate [load bench](cargo-load.md) retains its original characterization contract. | |
| 84 | ||
| 85 | ## Release and custody | |
| 86 | ||
| 87 | The shared payload port observes qualified delayed measurements, not current plant | |
| 88 | truth. Release requires current authority, matching site/recipient evidence, attached | |
| 89 | load, stable geometry and 26 distinct fresh captures. Both received observations and | |
| 90 | source captures must span at least 500 ms. Retained packets, retiming, clock/reference | |
| 91 | changes, stale gyros or scheduler gaps break readiness. Attitude, position, covariance, | |
| 92 | issue-time position, task, reference and bounded command lifetime are checked. | |
| 93 | ||
| 94 | The mechanism is dispatched at most once. Command intent, captured open/jammed state, | |
| 95 | receiver confirmation and carrier completion remain different observations. A policy | |
| 96 | refusal cannot become received custody through ambient receipt fields. Dispatch failure | |
| 97 | remains uncertain; uncertain/rejected terminal acknowledgements cancel the scoped | |
| 98 | operation before clearing it. Authority loss and close also cancel it idempotently. | |
| 99 | ||
| 100 | The model separates the actual point mass without resetting the carrier's motion, | |
| 101 | estimator or controller. The parcel follows a ballistic point trajectory to a plane. | |
| 102 | A receiver within the declared radius produces a fictional delayed receipt, which is | |
| 103 | then captured and transported. This model has no parcel drag, wind drift, deformation, | |
| 104 | collision scene, receiver authentication or measured release mechanism. | |
| 105 | ||
| 106 | ## Links and failures | |
| 107 | ||
| 108 | `createRedundantVehicleLinks` selects primary then backup for one captured vehicle, | |
| 109 | boot and session scope. It rejects foreign scope, replay, stale/future captures and | |
| 110 | invalid clock uncertainty. Age includes uncertainty and preserves the original capture | |
| 111 | epoch. Loss of both sources latches, including across an unobserved gap. A late packet | |
| 112 | does not silently restore authority. Labels are correlations, not authentication. | |
| 113 | The cargo fixture remains one carrier with boot 55/session 123; failover between its | |
| 114 | links is not fleet handover. | |
| 115 | ||
| 116 | Named cases include recipient absence, site blockage, mechanism jam, receipt loss, | |
| 117 | foreign receipt, primary/both-link loss, independent containment and faults during | |
| 118 | the alternate. Position, IMU, vehicle-sensor, RC, kill and host-loss cases also remain. | |
| 119 | The command's help lists every exact name. | |
| 120 | ||
| 121 | `after-release-` cases cover host, position, IMU, vehicle-sensor, RC, kill and both-link | |
| 122 | loss. `after-receipt-` cases cover host, kill and position loss. Injection starts 20 ms | |
| 123 | after the policy first observes the matching mechanism-open or received-custody state, | |
| 124 | rather than at a guessed mission time. `faultInjection` retains the observation, source capture, event, actual | |
| 125 | trigger and final physical epochs. An unreached anchor stays null and unmatched. | |
| 126 | ||
| 127 | These phase cases add a 1,000 ms independent settling probe after host execution ends. | |
| 128 | Only the board and physical plant continue; sensors, estimator, mission, payload and | |
| 129 | authority do not run. A parcel can reach the receiver in that interval while custody | |
| 130 | stays uncertain because no host received its receipt. A prior confirmed receipt remains | |
| 131 | received if the carrier later fails. Ground contact in a settling probe is not controlled | |
| 132 | carrier landing. After host loss the reported authority is its last stale snapshot, | |
| 133 | while the independent board expires its output lease. | |
| 134 | ||
| 135 | ## Library interface and energy limits | |
| 136 | ||
| 137 | Import `planCargoDelivery` from `resources/functions/drone/cargo/plan.ts`, | |
| 138 | `simulateCargoDelivery` and `cargoDeliverySummary` from `cargo/delivery.ts`, and | |
| 139 | `createCargoDeliveryCoordinator` from `cargo/coordinator.ts` under the same drone folder. | |
| 140 | The simulator accepts `{ configuration, scenario? }`; omitting configuration selects | |
| 141 | only the named demonstration fixture. The planner requires a complete declaration. | |
| 142 | The coordinator implements the existing `VehiclePayloadPort` over an explicitly modeled, | |
| 143 | synchronous mechanism adapter and returns detached custody/readiness snapshots. | |
| 144 | Full simulation results retain the complete runtime path and replayable mission trace. | |
| 145 | ||
| 146 | Energy is the existing declared maximum-power budget, including the worst normal or | |
| 147 | alternate graph and reserve. It is not a motor/battery electrical model, measured Wh, | |
| 148 | temperature limit, voltage-sag prediction or Pi performance result. Changing mass changes | |
| 149 | the actual modeled dynamics; it does not identify an electrical load law. A successful | |
| 150 | budget is conditional on that ceiling and is not measured endurance qualification. | |
| 151 | ||
| 152 | ## BVLOS operations evidence | |
| 153 | ||
| 154 | Country and intended operation must be established separately from library support. | |
| 155 | Sources below were checked October 24, 2026; inspect their current requirements for the | |
| 156 | actual operation. This software issues no authorization. | |
| 157 | ||
| 158 | The FAA's [Part 107 waiver guidance](https://www.faa.gov/uas/commercial_operators/part_107_waivers) | |
| 159 | identifies BVLOS and multiple-aircraft operation as distinct waiver subjects. Its | |
| 160 | [package-delivery guidance](https://www.faa.gov/uas/advanced_operations/package_delivery_drone) | |
| 161 | describes Part 135 certification, airspace authorization and applicable exemption/waiver | |
| 162 | work for BVLOS package delivery, with operating-area, communication and collision-avoidance | |
| 163 | evidence. A source-code license or simulated receipt supplies none of those approvals. | |
| 164 | ||
| 165 | EASA's [specific-category guidance](https://www.easa.europa.eu/en/the-agency/faqs/operational-authorisation-requirements-specific-category) | |
| 166 | distinguishes applicable standard-scenario declarations from national-authority operational | |
| 167 | authorizations supported by risk assessment, including SORA/PDRA paths and separate LUC | |
| 168 | privileges. A declaration route has its own aircraft and operational conditions. | |
| 169 | ||
| 170 | Before any proposed long-range operation, the operator's evidence case must bind the actual | |
| 171 | aircraft, crew, route, containment/alternate volumes, ground risks and authority approvals. | |
| 172 | It must address qualified detect-and-avoid and non-cooperative traffic, communication and | |
| 173 | navigation coverage/latency/loss, measured endurance and weather, release hardware and | |
| 174 | recipient/site procedures, fleet responsibility transfer, emergency response, maintenance | |
| 175 | and retained actual logs. These are pending engineering/operations deliverables here. | |
| 176 | Two modeled links, selected-person camera tracking and a range obstacle simulation do not | |
| 177 | establish an airspace detect-and-avoid system. | |
| 178 | ||
| 179 | ## Remaining issue scope | |
| 180 | ||
| 181 | [#25](https://github.com/stacksjs/drone/issues/25) remains open for actual distinct-vehicle | |
| 182 | fleet handover, richer endurance models/measurements, durable cargo/runtime reconciliation, | |
| 183 | physical release/recipient validation and the separate operational evidence case. | |
| 184 | The original acceptance scope is not reduced to passing named demonstrations. | |