ReviewOS

also looking at this

stacks/drone

fix: resolve source links through native drone docs

#40
Merged chris wants to merge codex/native-doc-links into main
56 files +179 -159
docs/architecture.mdmodified+15-15
Changes to docs/architecture.md
@@ -71,60 +71,60 @@ It uses the oldest heartbeat/position/battery receipt time for freshness. Physic
7171reports position health false and never transmits. SITL assumes the simulator's position estimator
7272is healthy; that assumption must never be carried into a physical adapter.
7373
74The wire codec is an experimental subset. [Shared acknowledged microservices](https://github.com/stacksjs/drone/blob/main/docs/driver-protocols.md) add bounded command, parameter and waypoint transfers; serial/TCP and complete firmware coverage remain open.
75Both external stacks are optional drivers. The [owned-stack ADR](https://github.com/stacksjs/drone/blob/main/docs/adr/0001-owned-autonomy.md) and
76[feature roadmap](https://github.com/stacksjs/drone/blob/main/docs/roadmap/README.md) define the replacement path. A future physical adapter needs verified estimator status, source identity, sequence/replay handling,
74The wire codec is an experimental subset. [Shared acknowledged microservices](driver-protocols.md) add bounded command, parameter and waypoint transfers; serial/TCP and complete firmware coverage remain open.
75Both external stacks are optional drivers. The [owned-stack ADR](adr/0001-owned-autonomy.md) and
76[feature roadmap](roadmap/README.md) define the replacement path. A future physical adapter needs verified estimator status, source identity, sequence/replay handling,
7777authenticated transport, link supervision, flight-controller configuration and hardware validation.
7878
7979## Native runtime bench slice
8080
8181The owned kernel and Pico 2 HAL live in `firmware/runtime/`, with the explicit C++17 exception in
82[ADR 2](https://github.com/stacksjs/drone/blob/main/docs/adr/0002-bench-runtime.md). Stacks owns the [CLI and protocol tools](https://github.com/stacksjs/drone/blob/main/docs/runtime.md) under
82[ADR 2](adr/0002-bench-runtime.md). Stacks owns the [CLI and protocol tools](runtime.md) under
8383`resources/functions/drone/runtime/`. The first profile is synthetic-sensor and neutral-output
8484only. It has no physical flight command path and does not replace estimation or vehicle controls.
8585
8686
87The optional [sensor bench profile](https://github.com/stacksjs/drone/blob/main/docs/sensors.md), recorded in [ADR 3](https://github.com/stacksjs/drone/blob/main/docs/adr/0003-sensor-bench.md),
87The optional [sensor bench profile](sensors.md), recorded in [ADR 3](adr/0003-sensor-bench.md),
8888adds original SPI/I2C/UART acquisition and a receive-only DS stream. TypeScript applies units,
8989calibration, clock uncertainty and independent health checks. The same pipeline runs against
9090recordings on the simulator clock. Replay snapshots are diagnostic; estimator fusion is issue #4.
9191
92The [owned estimator](https://github.com/stacksjs/drone/blob/main/docs/estimation.md), recorded in [ADR 4](https://github.com/stacksjs/drone/blob/main/docs/adr/0004-owned-estimator.md), consumes
92The [owned estimator](estimation.md), recorded in [ADR 4](adr/0004-owned-estimator.md), consumes
9393qualified sensor events on their capture epochs. It exposes tilt/relative-yaw, GNSS local NED and
9494separate pressure height with health/reset counters. It is independent of both external autopilots
9595and remains separate from control telemetry until heading, fusion and hardware validation exist.
9696
97The [owned control physics harness](https://github.com/stacksjs/drone/blob/main/docs/controls.md), recorded in [ADR 5](https://github.com/stacksjs/drone/blob/main/docs/adr/0005-simulated-multirotor-controls.md),
97The [owned control physics harness](controls.md), recorded in [ADR 5](adr/0005-simulated-multirotor-controls.md),
9898feeds modeled raw sensor records through the existing sensor pipeline and estimator into bounded
9999quad-X control. It declares initial simulation heading alignment and has no physical transport.
100100Plant truth is retained only for sensor synthesis and independent response evaluation.
101101
102The [owned authority supervisor](https://github.com/stacksjs/drone/blob/main/docs/authority.md), recorded in [ADR 6](https://github.com/stacksjs/drone/blob/main/docs/adr/0006-simulated-authority.md),
102The [owned authority supervisor](authority.md), recorded in [ADR 6](adr/0006-simulated-authority.md),
103103adds explicit arm/engage, fault revocation and a separate modeled output watchdog above that same
104104control path. A host-loss run stops all host execution while the modeled board clock continues.
105105Physical firmware and external adapters remain separate from these simulation-only frames.
106106
107[ADR 7](https://github.com/stacksjs/drone/blob/main/docs/adr/0007-driver-transactions.md) records shared external-driver transactions and the strict
107[ADR 7](adr/0007-driver-transactions.md) records shared external-driver transactions and the strict
108108separation between scripted UDP conformance, firmware SITL and physical evidence.
109109
110[ADR 8](https://github.com/stacksjs/drone/blob/main/docs/adr/0008-camera-payload-adapters.md) adds owned camera acquisition with bounded local IPC,
110[ADR 8](adr/0008-camera-payload-adapters.md) adds owned camera acquisition with bounded local IPC,
111111per-command clock synchronization, no automatic shutter retry and capture-epoch pose association.
112Native Stacks [payload commands](https://github.com/stacksjs/drone/blob/main/docs/payloads.md) expose replay and explicit Pi acquisition. Bus
112Native Stacks [payload commands](payloads.md) expose replay and explicit Pi acquisition. Bus
113113contracts remain configuration only; payloads cannot bypass the flight authority supervisor.
114114
115[ADR 9](https://github.com/stacksjs/drone/blob/main/docs/adr/0009-runtime-diagnostics.md) records bounded runtime-only journals with typed events,
115[ADR 9](adr/0009-runtime-diagnostics.md) records bounded runtime-only journals with typed events,
116116provenance digests, loss accounting and crash-prefix recovery. Native Stacks commands and a local
117[stx viewer](https://github.com/stacksjs/drone/blob/main/docs/diagnostics.md) share the pure verifier/replay projection. No replay path has a
117[stx viewer](diagnostics.md) share the pure verifier/replay projection. No replay path has a
118118vehicle transport, update/flash capability or runtime authority.
119119
120[ADR 10](https://github.com/stacksjs/drone/blob/main/docs/adr/0010-owned-missions.md) adds a versioned [owned mission engine](https://github.com/stacksjs/drone/blob/main/docs/missions.md) over
120[ADR 10](adr/0010-owned-missions.md) adds a versioned [owned mission engine](missions.md) over
121121the estimator/control/authority physics pipeline. Validated graphs emit position targets, never
122122arm themselves, and recover recorded prefixes into a supervised paused state. Task events and
123123local-position traces stay separate from physical payload IO and runtime-only diagnostic journals.
124124
125125## Shared owned vehicle execution
126126
127The [vehicle runtime](https://github.com/stacksjs/drone/blob/main/docs/vehicles.md) extends owned raw sensor and estimator execution to aerodynamic
127The [vehicle runtime](vehicles.md) extends owned raw sensor and estimator execution to aerodynamic
128128fixed-wing, differential ground and planar surface profiles. Explicit v2 missions share graph budgets,
129129replay, payload scope and authority lifecycle while each model owns its control and actuator units.
130130Fresh sessions isolate state. The common stx workspace inspects recorded estimated routes and