phase 29: add px4 sitl integration

Author: christopherkarani

.gitignore

@@ -19,3 +19,4 @@ summary.md
 .aegis/last.tmp
 .aegis/last.tmp.*
 .aegis/sessions/
+.aegis/edge/

README.md

@@ -12,13 +12,13 @@ Aegis is not a SaaS product, hosted dashboard, monetization layer, or telemetry
 
 ## Product Split
 
-Phase 23 introduced the monorepo product contract. Phase 24 hardened Aegis Core as the shared engine facade used by CLI and Edge. Phase 25 keeps the CLI as the stable desktop and CI product while hardening the post-split command surface. Phase 26 added Edge domain and safety schema contracts. Phase 27 added local Edge policy evaluation. Phase 28 adds a MAVLink gateway foundation for fake/in-memory protocol mediation:
+Phase 23 introduced the monorepo product contract. Phase 24 hardened Aegis Core as the shared engine facade used by CLI and Edge. Phase 25 keeps the CLI as the stable desktop and CI product while hardening the post-split command surface. Phase 26 added Edge domain and safety schema contracts. Phase 27 added local Edge policy evaluation. Phase 28 added a MAVLink gateway foundation for fake/in-memory protocol mediation. Phase 29 adds PX4 SITL integration for opt-in local simulation evidence:
 
 - **Aegis Core** (`packages/core/`): shared policy, decision, audit, event, schema, replay, redaction, fixture, red-team, capability, experimental ABI skeleton, and platform-independent utility contracts.
 - **Aegis CLI** (`packages/cli/`): the existing desktop and CI AI-agent runtime firewall exposed as the `aegis` binary.
-- **Aegis Edge** (`packages/edge/`): a drone and robotics safety-policy and audit runtime with local policy decisions and Phase 28 fake MAVLink gateway scenarios.
+- **Aegis Edge** (`packages/edge/`): a drone and robotics safety-policy and audit runtime with local policy decisions, fake MAVLink gateway scenarios, deterministic fake-PX4 scenarios, and opt-in PX4 SITL checks.
 
-Aegis Edge policy evaluation is active for local decisions, and MAVLink support is limited to fake-transport simulation/protocol mediation. It can validate Edge policies, evaluate command requests against fake vehicle state, inspect/classify MAVLink frames, run deterministic fake MAVLink scenarios, prepare Core audit events, and explain safety findings. It does not open real serial, UDP, PX4, ArduPilot, ROS2, SITL, or hardware endpoints. It is not a flight controller, not an autopilot replacement, not detect-and-avoid, and not regulatory approval or certification. It must not be used for real flight.
+Aegis Edge policy evaluation is active for local decisions. MAVLink fake transport remains deterministic, and PX4 SITL is opt-in local simulation only. Edge can validate policies, evaluate command requests against simulated vehicle state, inspect/classify MAVLink frames, run deterministic fake MAVLink and fake-PX4 scenarios, prepare Core audit events, and explain safety findings. It does not support ArduPilot SITL, ROS2 control, real hardware integration, or real-flight deployment. It is not a flight controller, not an autopilot replacement, not detect-and-avoid, and not regulatory approval or certification. It must not be used for real flight.
 
 ## Install
 

build.zig

@@ -215,6 +215,18 @@ pub fn build(b: *std.Build) void {
     });
     const run_phase28_mavlink_gateway_tests = b.addRunArtifact(phase28_mavlink_gateway_tests);
 
+    const phase29_px4_sitl_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("tests/phase29_px4_sitl.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{
+                .{ .name = "aegis_edge", .module = aegis_edge_mod },
+            },
+        }),
+    });
+    const run_phase29_px4_sitl_tests = b.addRunArtifact(phase29_px4_sitl_tests);
+
     const test_step = b.step("test", "Run unit tests");
     test_step.dependOn(&run_lib_tests.step);
     test_step.dependOn(&run_exe_tests.step);
@@ -230,6 +242,7 @@ pub fn build(b: *std.Build) void {
     test_step.dependOn(&run_phase26_edge_domain_tests.step);
     test_step.dependOn(&run_phase27_edge_policy_engine_tests.step);
     test_step.dependOn(&run_phase28_mavlink_gateway_tests.step);
+    test_step.dependOn(&run_phase29_px4_sitl_tests.step);
 
     const fuzz_tests = b.addTest(.{
         .root_module = b.createModule(.{

docs/README.md

@@ -4,7 +4,7 @@ Product package docs:
 
 - `../packages/core/README.md`: Aegis Core shared policy, decision, audit, replay, redaction, fixture, schema registry, experimental ABI skeleton, and capability contract.
 - `../packages/cli/README.md`: Aegis CLI desktop and CI AI-agent runtime firewall contract.
-- `../packages/edge/README.md`: Aegis Edge scaffold plus Phase 26 domain/schema contract for future drone and robotics policy/audit work. Aegis Edge is not a flight controller, not an autopilot replacement, not detect-and-avoid, not regulatory approval or certification, and must not be used for real flight.
+- `../packages/edge/README.md`: Aegis Edge domain, policy, MAVLink, and PX4 SITL simulation contract. Aegis Edge is not a flight controller, not an autopilot replacement, not detect-and-avoid, not regulatory approval or certification, and must not be used for real flight.
 - `edge/`: Edge domain model, coordinate frames, safety policy, and safety schema notes.
 
 Launch docs:

docs/edge/domain-model.md

@@ -12,7 +12,7 @@ Vehicle identity and platform fields are explicit:
 - `AdapterKind`: fake, MAVLink, ROS2, custom, or unknown.
 - `VehicleMode`, `ArmState`, and `ControlAuthority`.
 
-These are domain values. Phase 28 maps a supported subset of MAVLink messages into Edge command requests for fake/in-memory protocol mediation only. PX4, ArduPilot, ROS2, SITL, and hardware numeric integration remain unimplemented.
+These are domain values. Phase 28 maps a supported subset of MAVLink messages into Edge command requests for fake/in-memory protocol mediation. Phase 29 maps deterministic fake-PX4 and opt-in PX4 SITL simulation records into Edge state and command decisions. ArduPilot, ROS2, and hardware numeric integration remain unimplemented.
 
 ## Vehicle State
 

docs/edge/limitations.md

@@ -1,14 +1,13 @@
 # Edge Limitations
 
-Aegis Edge Phase 28 implements policy evaluation and a MAVLink gateway foundation for fake/in-memory protocol mediation. It is not command forwarding to a real flight controller.
+Aegis Edge Phase 29 implements policy evaluation, a MAVLink gateway foundation for fake/in-memory protocol mediation, deterministic fake-PX4 scenarios, and opt-in PX4 SITL simulation checks. It is not command forwarding to a real flight controller.
 
 Not implemented:
 
-- PX4 integration.
 - ArduPilot integration.
 - ROS2 integration.
-- PX4 SITL or ArduPilot SITL control.
-- Real serial or UDP MAVLink endpoints.
+- ArduPilot SITL control.
+- Real serial or hardware MAVLink endpoints.
 - Real hardware integration.
 - Real-flight deployment.
 - Customer hardware bench procedure.
@@ -17,6 +16,6 @@ Not implemented:
 - MAVLink signing key management or signing verification.
 - SaaS, monetization, telemetry, certification, or regulatory claims.
 
-Coordinate frames and altitude references must be explicit. Unsupported geospatial conversions fail clearly. Polygon geofences and dialect-specific fence messages are reserved but not enforced in Phase 28.
+Coordinate frames and altitude references must be explicit. Unsupported geospatial conversions fail clearly. Polygon geofences and dialect-specific fence messages are reserved but not enforced in Phase 29.
 
-Fake and simulation examples are deterministic policy/protocol fixtures. They are not flight validation and must not be used as real-flight readiness evidence.
+Fake, fake-PX4, and PX4 SITL examples are simulation fixtures. They are not flight validation and must not be used as real-flight readiness evidence.

docs/edge/mavlink-gateway.md

@@ -1,15 +1,15 @@
 # MAVLink Gateway
 
-Phase 28 implements the Aegis Edge MAVLink gateway foundation for fake/in-memory protocol mediation. It parses MAVLink frames, classifies supported messages, maps supported commands into Edge `CommandRequest` values, evaluates those requests through the Phase 27 policy engine, and records bounded audit events.
+Phase 28 implements the Aegis Edge MAVLink gateway foundation for fake/in-memory protocol mediation. Phase 29 reuses this gateway for PX4 SITL simulation scenarios. It parses MAVLink frames, classifies supported messages, maps supported commands into Edge `CommandRequest` values, evaluates those requests through the Phase 27 policy engine, and records bounded audit events.
 
-This is not real-flight readiness. The gateway does not open serial ports, UDP sockets, PX4 SITL, ArduPilot SITL, ROS2 endpoints, or customer hardware. It is for deterministic simulation, bench-oriented protocol review, and local tests.
+This is not real-flight readiness. The gateway does not open serial ports, ArduPilot SITL, ROS2 endpoints, or customer hardware. PX4 SITL use is opt-in local simulation only. The default path is deterministic fake transport for simulation, bench-oriented protocol review, and local tests.
 
 ## Gateway Modes
 
 - `observe`: parse, classify, audit, and forward valid messages in fake transport. Denied policy results are logged but not blocked.
 - `enforce`: evaluate mapped commands and block denied or approval-required messages because no operator approval runtime exists in Phase 28.
 - `ci` / `redteam`: non-interactive. `ask` becomes deny and unknown command sources fail closed.
-- `simulation`: reserved for fake transport scenarios. Provenance is labeled `fake_transport/simulation`.
+- `simulation`: fake transport or fake-PX4 scenarios. Provenance is labeled `fake_transport/simulation` for MAVLink fixtures or `fake_adapter` for fake-PX4 state.
 - `bench`: reserved for later non-flight bench work. It is not a real hardware procedure.
 - `disabled`: no forwarding.
 

docs/edge/mavlink-limitations.md

@@ -1,14 +1,13 @@
 # MAVLink Limitations
 
-Phase 28 is a gateway foundation, not a deployment package.
+Phase 28 is a gateway foundation, not a deployment package. Phase 29 adds PX4 SITL simulation through the `aegis-edge px4` command surface.
 
 Not implemented:
 
 - Real serial MAVLink endpoints.
 - Real UDP MAVLink endpoints.
-- PX4 integration.
 - ArduPilot integration.
-- PX4 SITL or ArduPilot SITL.
+- ArduPilot SITL.
 - ROS2 integration.
 - Real-flight deployment.
 - Customer hardware bench procedure.
@@ -20,6 +19,6 @@ Not implemented:
 - Autopilot replacement behavior.
 - Regulatory approval, certification, or airworthiness claims.
 
-MAVLink2 signing detection records whether a signing block is present. Verification is reported as unavailable because Phase 28 does not manage keys or verify signatures.
+MAVLink2 signing detection records whether a signing block is present. Verification is reported as unavailable because Aegis Edge does not manage keys or verify signatures in Phase 29.
 
 Mission handling is generic MAVLink transaction tracking only. It tracks count, sequence, duplicates, partial uploads, ACK, clear, set-current, completion, and denial state. It does not emulate PX4 or ArduPilot mission semantics.

docs/edge/px4-limitations.md

@@ -0,0 +1,24 @@
+# PX4 Limitations
+
+PX4 support in Phase 29 is simulation-only.
+
+Supported:
+
+- Deterministic fake-PX4 telemetry and command fixtures.
+- PX4 SITL configuration and honest doctor output.
+- MAVLink command mediation through existing Edge policy.
+- Redacted scenario audit/replay artifacts.
+- Opt-in PX4 SITL integration-test gating.
+
+Not supported:
+
+- Real drone hardware.
+- Real-flight deployment.
+- Customer hardware bench procedures.
+- ArduPilot SITL.
+- ROS2 control.
+- Detect-and-avoid.
+- Autopilot replacement behavior.
+- Regulatory approval, certification, or airworthiness claims.
+
+Fake-PX4 artifacts use `fake_adapter` provenance. PX4 SITL artifacts must use `sitl_px4` provenance. A fake adapter pass must never be presented as PX4 SITL success.

docs/edge/px4-scenarios.md

@@ -0,0 +1,20 @@
+# PX4 Scenarios
+
+PX4 scenarios are run with:
+
+```bash
+./zig-out/bin/aegis-edge px4 scenario run --policy <policy> --scenario <scenario> [--artifacts <dir>]
+```
+
+Checked-in deterministic scenarios live under `examples/edge/px4/scenarios/`:
+
+- `waypoint-outside-geofence-deny.yaml`
+- `land-allow.yaml`
+- `disable-failsafe-deny.yaml`
+- `mission-outside-geofence-deny.yaml`
+- `raw-actuator-deny.yaml`
+- `takeoff-low-battery-deny.yaml`
+
+Artifacts include scenario id, environment, endpoint metadata, command requests, policy decisions, forwarded/blocked status, safety findings, limitations, and redacted notes. `events.jsonl` and `replay.json` are written through the redaction path before persistence.
+
+Missing PX4 SITL produces a skip/unavailable result for SITL scenarios. It must not silently fall back to fake-PX4 and claim SITL success.