also looking at this

feat: model owned VTOL flight transitions

#78

Merged chris wants to merge codex/owned-vtol-flight-controls into main

13 files +1087 -33

docs/vehicles-vtol.mdmodified+64-8

Changes to docs/vehicles-vtol.md
		@@ -3,7 +3,8 @@
3	3	The owned lift-and-cruise model can execute a hover-only mission through the shared raw sensor,
4	4	estimator, mission, authority and independent output-lease runtime. It takes off vertically, reaches
5	5	a nearby hover waypoint and lands against fresh modeled contact evidence. Wing transitions and
6		cruise control are not implemented. This development profile is separate from the selectable
	6	cruise control are not implemented in this hover profile. A separate experimental library controller
	7	is described below. This development profile is separate from the selectable
7	8	profiles in the `/missions` workspace.
8	9
9	10	```sh
		@@ -37,7 +38,9 @@ The hover demonstration commands the pusher and three surfaces to zero. Calibrat
37	38	IMU/GNSS samples feed the owned estimator. The controller receives estimated pose, a current qualified
38	39	raw gyro capture and delayed contact measurements. Plant truth is used for sensor synthesis and
39	40	independent evaluation, never as controller input. Initial north heading and a flat contact plane
40		are declared simulation assumptions. Landing uses a 0.1 m below-plane target to obtain finite
	41	are declared simulation assumptions. A fictional skid friction coefficient of 0.5 supplies bounded
	42	horizontal braking from normal support at contact. It does not model impact impulses, gear deformation,
	43	tipping, damage or uneven terrain. Airborne motion receives no contact friction. Landing uses a 0.1 m below-plane target to obtain finite
41	44	contact; mission completion still requires estimated arrival, low speed, settling and fresh contact.
42	45
43	46	Contact and paused-ground neutral decisions occur after estimator/rate validation. A stale gyro
		@@ -51,14 +54,67 @@ fictional hover experiment. They are not identified electrical power, measured e
51	54	complete hybrid energy model. Neutral outputs during an airborne fault do not establish a safe
52	55	emergency landing. Physical flight commands remain disabled.
53	56
	57	## Explicit hover observation in library plans
	58
	59	Library plans can declare a VTOL-only `vtol-mode` task with `mode: 'hover'`, an explicit heading
	60	and a finite timeout. The held position must equal the request position. The mission emits a task, reference and epoch-bound request. The hover adapter
	61	requires fresh post-request contact, estimated pose and raw gyro sources, with a 200 ms stability
	62	dwell on both the monotonic decision clock and source coverage. It reports the oldest source capture epoch. The shared runtime delivers each controller
	63	response once on the next mission tick and retains it for replay. Initial contact holds all outputs
	64	neutral until observation is qualified. Unobserved headings expire, and this hover adapter reports
	65	cruise requests as aborted. This is a library prerequisite, not front/back transition control or a
	66	new CLI scenario. Existing hover-only recordings keep their prior shapes.
	67
	68	## Experimental lift-and-cruise library controller
	69
	70	`createVtolTransitionProfile()` in `resources/functions/drone/vehicles/vtol/transition-profile.ts`
	71	is a separate development experiment on the same owned runtime. Its nominal mission observes initial
	72	hover, takes off vertically to 15 m, requests a front transition, flies a cruise leg, requests back
	73	transition, returns to the back request's capture point, observes settled hover, and lands vertically.
	74	A turning leg also has an actual completed model campaign. This profile is not registered as a CLI
	75	scenario or selectable workspace profile.
	76
	77	The controller receives measured relative airspeed, differential pressure, airflow angles and modeled
	78	rotor/pusher response, together with the qualified raw gyro and estimated navigation. Delayed airflow
	79	angles are transformed through their matching capture-time attitude. The measured NED airflow vector
	80	is held to the decision and then expressed in the current gyro-predicted body attitude. This is a
	81	bounded synthetic observation approximation, not identified wind estimation or physical air-data
	82	calibration. Banked navigation follows the route while coordinated yaw follows the measured air
	83	course. Surface torque and residual rotor torque are allocated together; measured wing lift reduces
	84	collective rather than adding full rotor weight support on top of the wing.
	85
	86	Front confirmation requires sustained measured 12 to 14 m/s relative airflow, bounded angles,
	87	height/rate and less than 1 N of measured and commanded lift-rotor support. Both decision time and
	88	oldest-source coverage must qualify for 500 ms, including the attitude and gyro epochs used to
	89	transform delayed airflow. Ground speed or a timer alone cannot confirm cruise.
	90	A failed modeled pusher and an artificial co-moving-air fixture retain failed transition outcomes.
	91
	92	Back transition turns the pusher off and decelerates under the declared aerodynamic model before
	93	returning to the original capture point at a horizontal target speed bounded to 3 m/s. The nominal
	94	model needs about 38 seconds for deceleration, return and hover qualification. Observed hover also
	95	requires wrapped heading error within 0.1 rad for the complete 500 ms dwell. Hover/back requests
	96	therefore have a finite 45-second ceiling; front requests retain 15 seconds. The original 15-second
	97	back budget still fails without retry or a claimed landing. This is a virtual task allowance,
	98	not a wall-clock test timeout. The complete declared mission budget is 131,520 ms, or 43.84 Wh at its
	99	1200 W ceiling, with 100 Wh capacity and 30% reserve. These remain declared planning values, without
	100	a complete hybrid electrical-power law or measured battery identification.
	101
	102	The experiment keeps the 2 m transition-height deviation, 0.6 rad roll, 0.5 rad pitch and 22 m/s
	103	speed guards. Its own target range is bounded to 400 m. The quadcopter and hover development kernel's
	104	existing 3 m/s horizontal target and 100 m target-radius guards are unchanged. Source, capture-pose,
	105	reference and clock faults latch. Real modeled sensor loss, RC override, kill and host-loss campaigns
	106	cover front transition, cruise, back transition and post-back landing through the independent output
	107	lease. Neutral outputs during an airborne failure do not demonstrate a safe recovery or landing.
	108
54	109	## Remaining implementation
55	110
56		[Issue #12](https://github.com/stacksjs/drone/issues/12) remains open for explicit correlated
57		transition requests and observed outcomes, front/cruise/back control, airspeed and attitude
58		qualification, bounded transition abort/recovery, complete hybrid power/reserve accounting and
59		the common mission workspace. Full TECS/soaring, tiltrotor/tailsitter mechanisms, helicopters and
60		other airframe families remain separate work. Native board control, measured airframe identification,
61		HIL and physical flight require their own evidence.
	111	[Issue #12](https://github.com/stacksjs/drone/issues/12) remains open. The experimental nominal
	112	controller does not establish complete VTOL support. Phase pause/recovery, explicit bounded
	113	transition abort and landing, the complete hybrid power/reserve model, native transition CLI and
	114	the common mission workspace still require implementation and qualification. Wind campaigns and
	115	broader mission/envelope coverage remain necessary. Full TECS/soaring, tiltrotor/tailsitter mechanisms,
	116	helicopters and other airframe families remain separate work. Native board control, measured airframe
	117	identification, HIL and physical flight require their own evidence.
62	118
63	119	Read the [shared vehicle contract](vehicles.md), [fixed-wing model](vehicles-air.md) and
64	120	[authority contract](authority.md).