ReviewOS

also looking at this

stacks/drone

feat: model one point-load intake with conserved momentum

#99
Merged chris wants to merge codex/cargo-fleet-custody into main
45 files +3133 -169
docs/cargo-delivery.mdadded+215-0
Changes to docs/cargo-delivery.md
@@ -0,0 +1,215 @@
1# Modeled cargo delivery
2
3The owned quadcopter runtime can execute a delivery mission with a carried point mass,
4captured release observations, receiver confirmation, a finite alternate landing and two
5modeled communication sources. The raw IMU/GNSS feed, estimator, controls, authority and
6independent output watchdog are the same paths used by the other owned vehicle profiles.
7ArduPilot and PX4 are optional drivers and are not used by this simulation.
8
9This is software simulation. Physical outputs remain inhibited and identity is not
10authenticated. A modeled receiver receipt does not establish a real recipient, hardware
11release, 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
21The standalone `drone cargo:mission` command has the same arguments. The request file is
22required. 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).
24There 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
36Down is positive. The receiver and alternate down coordinate must be zero. The carrier
37starts and returns at the local origin. Its modeled structural datum rests 0.1 m above
38the ground; qualified contact, rather than an invented exact zero position, completes
39landing. Sites and routes must fit the existing 12 m horizontal and -5 to 0 m down fence.
40This flat local world does not implement real terrain, arbitrary geodetic origins or
41long-range navigation.
42
43Site radius is 0.1 to 2 m. Site and recipient identifiers use lowercase ASCII letters,
44digits and hyphens, beginning with a letter, at most 64 characters; the container is
45limited to 40 characters by the carried-body model. Records reject extra fields,
46accessors and missing values. Tuples require three finite own data elements.
47
48The complete owned mission validator checks normal and alternate graph duration and
49reserve before a plant is allocated. The graph includes takeoff, destination, one
50material-drop request, return/landing, and a one-way alternate approach/landing after
51payload failure. No failure path retries release. Its fixed task deadlines give a worst
52case of 81,520 ms. The declared power ceiling must be at least 600 W; native mission
53capacity, reserve and power ceilings still apply.
54
55The 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%
57reserve. 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
62its final LF. It retains the admitted configuration, actual outcome, load, parcel,
63custody, 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
72The request is a regular file bounded to 16,384 bytes, decoded with strict UTF8. A final
73symlink is refused; parent paths are followed. Reading is not path authorization or an
74atomic snapshot of concurrent file mutation. Accept results only after both streams
75reach EOF and the actual exit status is known. A failed output write can leave a prefix.
76JSON parsing uses native last-key-wins semantics. The CLI does not persist a full runtime
77journal, canonical signed request or authenticated output.
78
79The existing `cargo:deliver --scenario <name>` command remains a set of closed
80demonstrations with its original 100 g forward load. It exits 0 for matched fault
81demonstrations as well as the matched nominal route; it does not mean a parcel was
82delivered. Invalid input, unmatched demonstrations and output failures exit 1.
83The separate [load bench](cargo-load.md) retains its original characterization contract.
84
85## Release and custody
86
87The shared payload port observes qualified delayed measurements, not current plant
88truth. Release requires current authority, matching site/recipient evidence, attached
89load, stable geometry and 26 distinct fresh captures. Both received observations and
90source captures must span at least 500 ms. Retained packets, retiming, clock/reference
91changes, stale gyros or scheduler gaps break readiness. Attitude, position, covariance,
92issue-time position, task, reference and bounded command lifetime are checked.
93
94The mechanism is dispatched at most once. Command intent, captured open/jammed state,
95receiver confirmation and carrier completion remain different observations. A policy
96refusal cannot become received custody through ambient receipt fields. Dispatch failure
97remains uncertain; uncertain/rejected terminal acknowledgements cancel the scoped
98operation before clearing it. Authority loss and close also cancel it idempotently.
99
100The model separates the actual point mass without resetting the carrier's motion,
101estimator or controller. The parcel follows a ballistic point trajectory to a plane.
102A receiver within the declared radius produces a fictional delayed receipt, which is
103then captured and transported. This model has no parcel drag, wind drift, deformation,
104collision scene, receiver authentication or measured release mechanism.
105
106## Links and failures
107
108`createRedundantVehicleLinks` selects primary then backup for one captured vehicle,
109boot and session scope. It rejects foreign scope, replay, stale/future captures and
110invalid clock uncertainty. Age includes uncertainty and preserves the original capture
111epoch. Loss of both sources latches, including across an unobserved gap. A late packet
112does not silently restore authority. Labels are correlations, not authentication.
113The cargo fixture remains one carrier with boot 55/session 123; failover between its
114links is not fleet handover.
115
116Named cases include recipient absence, site blockage, mechanism jam, receipt loss,
117foreign receipt, primary/both-link loss, independent containment and faults during
118the alternate. Position, IMU, vehicle-sensor, RC, kill and host-loss cases also remain.
119The command's help lists every exact name.
120
121`after-release-` cases cover host, position, IMU, vehicle-sensor, RC, kill and both-link
122loss. `after-receipt-` cases cover host, kill and position loss. Injection starts 20 ms
123after the policy first observes the matching mechanism-open or received-custody state,
124rather than at a guessed mission time. `faultInjection` retains the observation, source capture, event, actual
125trigger and final physical epochs. An unreached anchor stays null and unmatched.
126
127These phase cases add a 1,000 ms independent settling probe after host execution ends.
128Only the board and physical plant continue; sensors, estimator, mission, payload and
129authority do not run. A parcel can reach the receiver in that interval while custody
130stays uncertain because no host received its receipt. A prior confirmed receipt remains
131received if the carrier later fails. Ground contact in a settling probe is not controlled
132carrier landing. After host loss the reported authority is its last stale snapshot,
133while the independent board expires its output lease.
134
135## Library interface and energy limits
136
137Import `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.
140The simulator accepts `{ configuration, scenario? }`; omitting configuration selects
141only the named demonstration fixture. The planner requires a complete declaration.
142The coordinator implements the existing `VehiclePayloadPort` over an explicitly modeled,
143synchronous mechanism adapter and returns detached custody/readiness snapshots.
144Full simulation results retain the complete runtime path and replayable mission trace.
145
146Energy is the existing declared maximum-power budget, including the worst normal or
147alternate graph and reserve. It is not a motor/battery electrical model, measured Wh,
148temperature limit, voltage-sag prediction or Pi performance result. Changing mass changes
149the actual modeled dynamics; it does not identify an electrical load law. A successful
150budget is conditional on that ceiling and is not measured endurance qualification.
151
152## Point-load intake prerequisite
153
154`createReceivingRigidBody` in `controls/physics.ts` adds an empty declared joint for a
155future parcel. Supply `expectedPointLoad: { id, massKg, forwardM }`; the mass and offset
156bounds match the carried-load model. Its `awaiting` phase has the base body's actual
157mass/inertia. `intakePoint()` returns only joint position and velocity, not a parcel or
158custody evidence.
159
160`attachParcel({ id, massKg, positionM, velocityMps })` accepts an existing modeled point
161parcel only at the current joint position, equal component by component. Identity and
162mass must match the declaration. The caller must move its one physical-world parcel
163there; this primitive does not transport, copy or globally own it. Malformed own-data
164records throw without changing the body. Valid foreign or noncoincident parcels are
165refused without consuming the joint.
166
167Capture conserves total linear/angular momentum and applies a perfectly inelastic point
168joint. Structural position, orientation and actual motors remain continuous; a non-co-moving
169parcel can impart a genuine velocity/angular-rate impulse. Captured mass changes the actual
170subsequent dynamics, CG and inertia. The event retains detached before/after state, incoming
171parcel and raw kinetic/potential energy accounting. Dissipation is mechanical energy,
172not battery Wh or an identified mechanism efficiency. Tiny binary64 negative loss within
173the reported numerical tolerance is retained rather than clamped.
174
175The joint accepts once, can later separate through the existing zero-ejection model and
176cannot refill after separation. The legacy `createRigidBody` carried-load interface keeps
177its original phase/method contract. [ADR 0036](adr/0036-point-load-intake.md) gives the model
178and limits. This primitive supplies no finite-duration contact forces or impact IMU sample,
179release/intake acknowledgement, station handling, authorization or fleet custody handover.
180Those integrations remain open under issue #25.
181
182## BVLOS operations evidence
183
184
185Country and intended operation must be established separately from library support.
186Sources below were checked October 24, 2026; inspect their current requirements for the
187actual operation. This software issues no authorization.
188
189The FAA's [Part 107 waiver guidance](https://www.faa.gov/uas/commercial_operators/part_107_waivers)
190identifies BVLOS and multiple-aircraft operation as distinct waiver subjects. Its
191[package-delivery guidance](https://www.faa.gov/uas/advanced_operations/package_delivery_drone)
192describes Part 135 certification, airspace authorization and applicable exemption/waiver
193work for BVLOS package delivery, with operating-area, communication and collision-avoidance
194evidence. A source-code license or simulated receipt supplies none of those approvals.
195
196EASA's [specific-category guidance](https://www.easa.europa.eu/en/the-agency/faqs/operational-authorisation-requirements-specific-category)
197distinguishes applicable standard-scenario declarations from national-authority operational
198authorizations supported by risk assessment, including SORA/PDRA paths and separate LUC
199privileges. A declaration route has its own aircraft and operational conditions.
200
201Before any proposed long-range operation, the operator's evidence case must bind the actual
202aircraft, crew, route, containment/alternate volumes, ground risks and authority approvals.
203It must address qualified detect-and-avoid and non-cooperative traffic, communication and
204navigation coverage/latency/loss, measured endurance and weather, release hardware and
205recipient/site procedures, fleet responsibility transfer, emergency response, maintenance
206and retained actual logs. These are pending engineering/operations deliverables here.
207Two modeled links, selected-person camera tracking and a range obstacle simulation do not
208establish an airspace detect-and-avoid system.
209
210## Remaining issue scope
211
212[#25](https://github.com/stacksjs/drone/issues/25) remains open for actual distinct-vehicle
213fleet handover, richer endurance models/measurements, durable cargo/runtime reconciliation,
214physical release/recipient validation and the separate operational evidence case.
215The original acceptance scope is not reduced to passing named demonstrations.