docs: add Phase 1 ADRs and update PROJECT.md with completed decisions

ADR 0002: hexagonal/ports-and-adapters architecture — components/ layout,
  protocol.py per component, composition root, core/ for concentrated math.
ADR 0003: @dataclass(slots=True, frozen=True) on hot path; Pydantic retained
  only at REST/config/DB boundaries. Pose/GPSPoint migration deferred to Phase 2.
ADR 0004: Stage 2 as independent iteration — own phases 1-6, own requirements,
  stage1 code treated as MVP starting capital.

PROJECT.md: Stage 2 Key Decisions updated from Pending → Accepted with Phase 1
  implementation notes, deferred work list, and final architecture summary.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -17,3 +17,7 @@ build/
 # Env
 .env
 *.env
+
+# Local planning/docs (not for the repo)
+docs-Lokal/
+.planning/

.planning/PROJECT.md

@@ -1,98 +1,175 @@
-# GPS-Denied Onboard Navigation System
+# GPS-Denied Onboard Navigation System — Stage 2
 
 ## What This Is
 
 Real-time GPS-independent position estimation system for a fixed-wing UAV operating in GPS-denied/spoofed environments (flat terrain, Ukraine). Runs onboard a Jetson Orin Nano Super (8GB shared, 67 TOPS). Fuses visual odometry (cuVSLAM), satellite image matching (TensorRT FP16), and IMU via an ESKF to output MAVLink GPS_INPUT to an ArduPilot flight controller at 5-10Hz, while also streaming position and confidence over SSE to a ground station.
 
+## Stage 2 Iteration
+
+**Stage 2 is a self-contained iteration of the project.** It is NOT a continuation of Stage 1's phase numbering — it has its own roadmap (Phases 1–6), its own requirements list, and its own success criteria. Each stage is conceptually a new pass at the system: same problem, same end goal, fresh decisions about HOW.
+
+**Stage 2 starting capital:**
+
+- **From stage1 (own work):** The full v1 pipeline as MVP — ESKF (15-state), cuVSLAM/ORB VO, satellite matching + GPR, MAVLink GPS_INPUT, pipeline orchestration, SITL harness, accuracy benchmarks, 195 passing tests. Treated as **MVP, not production** — refactoring is allowed and expected.
+- **From try02 (parallel team):** Concept-level ideas only — Safety Anchor State Machine, Geometry-Gated Anchor Verifier, Flight Data Recorder, Conditional Multi-Scale VPR, dual-channel MAVLink design, formal Acceptance Criteria document with numeric thresholds, structured test taxonomy.
+- **From real-flight data:** Azaion 10.05.2026 dataset (tlog + 6min video + 9.5Hz GPS ground truth) as integration fixture.
+
+**Stage 2 is free to:**
+
+- Reorganize the codebase (hexagonal layout) — no production lock-in
+- Replace, swap, or rebuild components — only AC-driven test outcomes are sacred
+- Change the architecture wholesale if a better path emerges mid-stage
+- Diverge from try02's choices where the evidence supports it (e.g., reject BASALT in favor of cuVSLAM, reject Pydantic on hot path)
+
+**Stage 2 archive:** `_planning/archive/v1.0/` preserves stage1's PROJECT.md, REQUIREMENTS.md, ROADMAP.md, and Phase 1 artifacts as historical record.
+
 ## Core Value
 
 The flight controller must receive valid MAVLink GPS_INPUT at 5-10Hz with position accuracy ≤50m for 80% of frames — without this, the UAV cannot navigate in GPS-denied airspace.
 
-## Requirements
+## Stage 2 Goal
 
-### Validated
+Refactor the inherited stage1 MVP into a hexagonal/ports-and-adapters architecture with explicit DI composition root, integrate selected concept-level ideas from `try02`, formalize acceptance criteria with testable numerics, and add a real-flight integration fixture (Azaion 10.05.2026).
 
-- ✓ FastAPI service scaffold with SSE streaming — existing
-- ✓ FlightProcessor orchestrator with NORMAL/LOST/RECOVERY state machine — existing
-- ✓ CoordinateTransformer (GPS↔ENU, pixel→camera→body→NED→WGS84) — existing
-- ✓ SatelliteDataManager (tile fetch, diskcache, GeoHash lookup) — existing
-- ✓ ImageInputPipeline (frame queue, batch validation, storage) — existing
-- ✓ SQLAlchemy async DB layer (flights, waypoints, frames, results) — existing
-- ✓ Pydantic schema contracts for all inter-component data — existing
-- ✓ ABC interfaces for all core components (VO, GPR, metric, graph) — existing
+## Stage 2 Target Features
 
-### Active
+**Architecture:**
+- Hexagonal layout — `src/gps_denied/components/{vio, satellite_matcher, gpr, anchor_verifier, safety_state, flight_recorder, mavlink_io, coordinate_transforms}/` with `protocol.py` + concrete impls per component
+- Hot-path types as `@dataclass(slots=True, frozen=True)` for `FrameState`, `IMUSample`, `PositionEstimate`; Pydantic kept only at REST/config/DB boundaries
+- Composition root `pipeline/composition.py` with explicit DI for env-specific wiring (jetson/x86_dev/ci/sitl)
+- Per-environment config — `config/{jetson,x86_dev,ci,sitl}.yaml` driven by pydantic-settings
+- `core/` retained for concentrated math (ESKF, factor graph, RANSAC) — single-file pure functions
 
-- [ ] ESKF implementation (15-state error-state Kalman filter: IMU prediction + VO update + satellite update + covariance propagation)
-- [ ] MAVLink GPS_INPUT output (pymavlink, UART/UDP, 5-10Hz loop, ESKF state→GPS_INPUT field mapping)
-- [ ] Real VO implementation (cuVSLAM on Jetson / OpenCV ORB stub on dev for CI)
-- [ ] Real TensorRT inference (SuperPoint+LightGlue for VO, XFeat for satellite matching — FP16 on Jetson)
-- [ ] Satellite feature matching pipeline (tile selection by ESKF uncertainty, RANSAC homography, WGS84 extraction)
-- [ ] GlobalPlaceRecognition implementation (AnyLoc/DINOv2 candidate retrieval, FAISS index, tile scoring)
-- [ ] FactorGraph implementation (pose graph with VO edges + satellite anchor nodes, optimization loop)
-- [ ] FailureRecoveryCoordinator (tracking loss detection, re-init protocol, operator re-localization hint)
-- [ ] End-to-end pipeline wiring (processor.process_frame → VO → ESKF → satellite → GPS_INPUT)
-- [ ] Docker SITL test harness (ArduPilot SITL, camera replay, tile server mock, CI integration)
-- [ ] Confidence scoring and GPS_INPUT fix_type mapping (HIGH/MEDIUM/LOW → fix_type 3/2/0)
-- [ ] Object GPS localization endpoint (POST /objects/locate with gimbal angle projection)
+**try02 concept integration:**
+- Acceptance Criteria document — formal AC-1.x…AC-NEW-x with numeric thresholds, validation methods, test linkage
+- Safety Anchor State Machine — separate layer over ESKF owning `source_label` (`satellite_anchored`/`vo_extrapolated`/`dead_reckoned`), monotonic covariance growth, anchor age, tile write eligibility
+- Geometry-gated Anchor Verifier — formal accept/reject gates (inliers, MRE, reprojection error) before anchor enters ESKF
+- Flight Data Recorder (FDR) — append-only event log with bounded segment storage and health states
+- Conditional VPR invocation — DINOv2 forward only on re-loc triggers; steady-state geometric prior
+- Multi-scale VPR chunks — 600-800m ground-footprint chunks at 40-50% overlap, decoupled from storage tiles, fine (z=20) + coarse (z=17) scales
+- Source label + anchor_age_ms emitted in every GPS_INPUT estimate
+- Visual blackout handling — switch to `dead_reckoned` ≤400ms, monotonic covariance growth, `VISUAL_BLACKOUT_IMU_ONLY` STATUSTEXT @ 1-2Hz
+- Spoofing-promotion latency monitor — promote own estimate to FC primary within <3s of detected real-GPS health drop
+- Test taxonomy — `tests/{unit,integration,blackbox,sitl,e2e}/`
+- Dual-channel MAVLink design — `GPS_INPUT` primary (v1 only), `ODOMETRY` auxiliary scaffolded behind feature flag for v1.1
+- Structured JSON logging with `correlation_id` (frame_id) per-frame
+- CLI tool `gps_denied replay --tlog ... --video ...`
+- Real-flight integration fixture — Azaion 10.05.2026 as `tests/integration/azaion_flight/`
 
-### Out of Scope
+## Stage 2 Explicit Non-Goals
 
-- TensorRT engine building tooling — engines are pre-built offline, system only loads them
-- Google Maps tile download tooling — tiles pre-cached before flight, not streamed live
-- Full ArduPilot integration testing on hardware — Jetson hardware validation is post-v1
-- Mobile/web ground station UI — SSE stream is consumed by external systems
+- BASALT VIO backend — cuVSLAM remains primary (aarch64) with ORB-SLAM3 as CI baseline
+- Pydantic on the per-frame hot path — dataclasses replace it
+- Mandatory PostgreSQL — SQLite remains the embedded default
+- Microservice processes / IPC — single-process architecture preserved
+- Folder-per-component split for `core/` math files — ESKF/factor graph stay concentrated
+- Mid-flight tile generation + write-back to Suite (AC-8.4) — deferred to Stage 3
+- Production hardware validation on Jetson — deferred to Stage 3
+
+## Future Stages (parking lot)
+
+- **Stage 3 candidates:** Jetson hardware validation, mid-flight tile generation + Suite write-back, ODOMETRY channel enabled, AC-NEW-1 cold-boot benchmark, BASALT evaluation if cuVSLAM blockers emerge
+
+## Out of Scope (across all stages, unless re-opened)
+
+- TensorRT engine building tooling — engines are pre-built offline
+- Google Maps tile download tooling — tiles pre-cached before flight
+- Mobile/web ground station UI — SSE consumed by external systems
 - Multi-UAV coordination — single UAV instance only
 
 ## Context
 
-**Hardware target:** Jetson Orin Nano Super (8GB LPDDR5 shared, JetPack 6.2.2, CUDA 12.6, TRT 10.3.0). All development happens on x86 Linux; cuVSLAM and TRT are Jetson-only — dev machine uses OpenCV ORB stub and MockInferenceEngine.
+**Hardware target:** Jetson Orin Nano Super (8GB LPDDR5 shared, JetPack 6.2.2, CUDA 12.6, TRT 10.3.0). Development on x86 Linux; cuVSLAM and TRT are Jetson-only — dev/CI uses OpenCV ORB stub and MockInferenceEngine.
 
-**Camera:** ADTI 20L V1 (5456×3632, APS-C, 16mm lens, nadir fixed, 0.7fps). AI detection camera: Viewpro A40 Pro (separate).
+**Camera (target):** ADTI 20L V1 (5456×3632, APS-C, 16mm lens, nadir fixed, 0.7fps). AI detection camera: Viewpro A40 Pro (separate).
 
-**Flight controller:** ArduPilot via MAVLink UART. System sends GPS_INPUT; receives IMU (200Hz) and GLOBAL_POSITION_INT (1Hz) from FC.
+**Camera (Azaion fixture):** Multirotor gimbal EO+IR split-screen with HUD overlay, 1280×720 @ 30fps. Used for integration testing only — does not represent target deployment camera.
 
-**Key latency budget:** <400ms end-to-end per frame (camera @ 0.7fps = 1430ms window).
+**Flight controller:** ArduPilot via MAVLink UART. System sends GPS_INPUT; receives IMU (200Hz target / 9.7Hz in Azaion fixture) and GLOBAL_POSITION_INT (1Hz) from FC.
 
-**Existing scaffold:** ~2800 lines of Python code exist as a well-structured scaffold. All modules are present with ABC interfaces and schemas, but critical algorithmic kernels (ESKF, real VO, TRT inference, MAVLink) are missing or mocked.
+**Key latency budget:** <400ms end-to-end per frame.
 
-**Test data:** 60 UAV frames (AD000001-AD000060.jpg), coordinates.csv with ground-truth GPS, expected_results/position_accuracy.csv. 43 documented test scenarios across 7 categories.
+**Stage 1 inheritance:** ~7,800 lines of working Python code with 195 passing tests. All algorithmic kernels (ESKF, VO, GPR, MAVLink, factor graph) implemented. Stage 2 starts from this codebase on branch `stage2` (HEAD = stage1).
+
+**Reference branch:** `try02` is checked out as a worktree at `../gps-denied-onboard-try02/` for concept harvesting. We do NOT merge from try02 — we read it for ideas and re-implement what fits.
 
 ## Constraints
 
-- **Performance**: <400ms/frame end-to-end, <8GB RAM+VRAM — non-negotiable for real-time flight
-- **Hardware**: cuVSLAM v15.0.0 (aarch64-only wheel) — stub interface required for CI
-- **Platform**: JetPack 6.2.2, Python 3.10+, TensorRT 10.3.0, CUDA 12.6
-- **Navigation accuracy**: 80% frames ≤50m, 60% frames ≤20m, max drift 100m between satellite corrections
-- **Resilience**: Handle sharp turns (disconnected VO segments), 3+ consecutive satellite match failures
+- **Performance:** <400ms/frame end-to-end p95, <8GB RAM+VRAM — non-negotiable
+- **Hardware:** cuVSLAM v15.0.0 (aarch64-only wheel) — Protocol with stub on x86
+- **Platform:** JetPack 6.2.2, Python 3.10+, TensorRT 10.3.0, CUDA 12.6
+- **Navigation accuracy:** 80% frames ≤50m, 60% frames ≤20m, max drift 100m between satellite corrections
+- **Resilience:** Handle sharp turns (disconnected VO segments), 3+ consecutive satellite match failures, visual blackout, GPS spoofing promotion <3s
+- **Regression floor:** All 195 stage1 passing tests must continue to pass after refactor
 
-## Key Decisions
+## Stage 2 Key Decisions
 
 | Decision | Rationale | Outcome |
 |----------|-----------|---------|
-| ESKF over EKF/UKF | 15-state error-state formulation avoids quaternion singularities, standard for INS | — Pending |
-| XFeat over LiteSAM for satellite matching | LiteSAM may exceed 400ms budget on Jetson; XFeat is faster | — Pending (benchmark required) |
-| OpenCV ORB stub for dev/CI | cuVSLAM is aarch64-only; CI must run on x86 | — Pending |
-| AnyLoc/DINOv2 for GPR | Validated on UAV-VisLoc benchmark (17.86m RMSE) | — Pending |
-| diskcache + GeoHash for tiles | O(1) tile lookup, no DB overhead, LRU eviction | ✓ Good |
-| AsyncSQLAlchemy + aiosqlite | Non-blocking DB for async FastAPI service | ✓ Good |
+| Hexagonal layout with `components/` folders | Clear ownership per swappable backend, native bridges colocate with adapter | ✓ Phase 1 |
+| `@dataclass(slots=True, frozen=True)` on hot path, Pydantic at boundaries only | Avoid try02's per-frame Pydantic latency cost; validate where it catches bugs (REST input, config) | ✓ Phase 1 (hot_types/ scaffolded; full migration Phase 2) |
+| Explicit DI composition root | One file wires environment-specific implementations; tests pass mock dependencies | ✓ Phase 1 (`pipeline/composition.py:build_pipeline`) |
+| Adopt try02 concept ideas, reject try02 layout details | Take Safety Anchor / Anchor Verifier / FDR / Conditional VPR; reject Pydantic-on-hot-path, BASALT | ✓ Adopted — Phases 3–5 |
+| Take try02 acceptance criteria with numeric thresholds | Their AC-1.x…AC-NEW-x is more rigorous than stage1's drafts; bind every AC to ≥1 test | ✓ Adopted — Phase 2 |
+| Test taxonomy `unit/integration/blackbox/sitl/e2e` | Clarifies CI-on-push vs PR vs nightly vs hardware-only test runs | ✓ Phase 2 |
+| Stage as iteration, not phase continuation | Each stage = own roadmap, own phase numbering, own success criteria | ✓ Adopted |
+
+## Phase 1 Outcome (2026-05-11, completed)
+
+**ARCH-01..07 all satisfied.** 216 tests pass (baseline 195+21 new = 216), 0 failures, accuracy benchmarks unchanged.
+
+### What was built
+
+**Components scaffold** (`src/gps_denied/components/`):
+- `vio/` — `protocol.py` + `orbslam_backend.py` + `cuvslam_backend.py` + `factory.py`; `core/vo.py` is a shim
+- `gpr/` — `protocol.py` + `faiss_gpr.py` (inline numpy fallback preserved); `core/gpr.py` is a shim
+- `satellite_matcher/` — `protocol.py` + `local_tile_loader.py` + `metric_refinement.py`; `core/satellite.py`, `core/metric.py` are shims
+- `mavlink_io/` — `protocol.py` + `pymavlink_bridge.py` + `mock_mavlink.py`; `core/mavlink.py` is a shim (re-exports private helpers `_confidence_to_fix_type`, `_eskf_to_gps_input`, `_unix_to_gps_time`)
+- `anchor_verifier/`, `safety_state/`, `flight_recorder/`, `coordinate_transforms/` — Protocol stubs only (Phases 3–5)
+
+**Hot-path types** (`src/gps_denied/hot_types/`): `FrameState`, `IMUSample`, `PositionEstimate`, `VOEstimate`, `SatelliteAnchor` as `@dataclass(slots=True, frozen=True)`. Schemas shimmed to re-export. `Pose` stays Pydantic (mutation sites in `factor_graph.py` lines 182–297); `GPSPoint` stays Pydantic. Full hot-path migration deferred to Phase 2.
+
+**Pipeline package** (`src/gps_denied/pipeline/`):
+- `orchestrator.py` — `FlightProcessor` (moved from `core/processor.py`)
+- `image_input.py`, `result_manager.py`, `sse_streamer.py` (moved from `core/`)
+- `composition.py` — `build_pipeline(env: Literal["jetson","x86_dev","ci","sitl"]) -> FlightProcessor`
+
+**Composition root**: wires 10 components; lazy imports inside function body to avoid circular imports; Jetson env → `prefer_cuvslam=True`, `prefer_mono_depth=True`; other envs → mocks.
+
+**Config**: `AppSettings.env` Literal field + `RuntimeConfig = AppSettings` alias. `pydantic-settings YamlConfigSettingsSource` loads `config/{env}.yaml`. `pyyaml>=6.0` declared.
+
+**ABC→Protocol sweep**: 6 interfaces converted to `typing.Protocol` with `@runtime_checkable`:
+`IFactorGraphOptimizer`, `IRouteChunkManager`, `IFailureRecoveryCoordinator`, `IModelManager`, `IImageMatcher`, + all 8 component Protocols from `components/*/protocol.py`.
+
+**`core/` retained** for concentrated math: `eskf.py`, `factor_graph.py`, `coordinates.py`, `chunk_manager.py`, `recovery.py`, `rotation.py`, `models.py`.
+
+**Shim policy**: every moved file leaves a re-export shim at its old path. Tests import from old paths — shims keep them green. Shim removal is Phase 2 work.
+
+### Deferred to Phase 2
+
+- Full hot-path type migration (`Pose`, `GPSPoint`, remaining Pydantic models on frame path)
+- Test reorganization to `tests/{unit,integration,blackbox,sitl,e2e}/`
+- Shim removal from `core/`
+- YAML config enrichment with env-specific overrides (MAVLink connection strings, tile dirs)
+
+## Stage 1 Decisions Inherited (validated, kept)
+
+| Decision | Outcome |
+|----------|---------|
+| ESKF over EKF/UKF | ✓ Stage 1 |
+| XFeat over LiteSAM for satellite matching | ✓ Stage 1 |
+| OpenCV ORB stub for dev/CI; cuVSLAM on Jetson | ✓ Stage 1 |
+| AnyLoc/DINOv2 for GPR | ✓ Stage 1 |
+| diskcache + GeoHash for tiles | ✓ Stage 1 |
+| AsyncSQLAlchemy + aiosqlite | ✓ Stage 1 |
 
 ## Evolution
 
-This document evolves at phase transitions and milestone boundaries.
+Each stage is its own iteration with its own PROJECT.md, REQUIREMENTS.md, ROADMAP.md. At stage completion:
 
-**After each phase transition** (via `/gsd:transition`):
-1. Requirements invalidated? → Move to Out of Scope with reason
-2. Requirements validated? → Move to Validated with phase reference
-3. New requirements emerged? → Add to Active
-4. Decisions to log? → Add to Key Decisions
-5. "What This Is" still accurate? → Update if drifted
-
-**After each milestone** (via `/gsd:complete-milestone`):
-1. Full review of all sections
-2. Core Value check — still the right priority?
-3. Audit Out of Scope — reasons still valid?
-4. Update Context with current state
+1. Snapshot current PROJECT.md / REQUIREMENTS.md / ROADMAP.md / phases/ → `.planning/archive/v[X.Y]/`
+2. Open new stage with fresh roadmap (Phase 1 of the new stage)
+3. Carry forward only validated decisions and unresolved Future-stages items
 
 ---
-*Last updated: 2026-04-01 after initialization*
+*Stage 2 opened: 2026-05-10*

.planning/REQUIREMENTS.md

@@ -1,157 +1,176 @@
-# Requirements: GPS-Denied Onboard Navigation System
+# Requirements: GPS-Denied Onboard Navigation System — Stage 2
 
-**Defined:** 2026-04-01
+**Defined:** 2026-05-10
+**Stage:** 2 (independent iteration)
+**Branch:** `stage2` (HEAD = stage1; v1.0 archived)
 **Core Value:** The flight controller must receive valid MAVLink GPS_INPUT at 5-10Hz with position accuracy ≤50m for 80% of frames — without this, the UAV cannot navigate in GPS-denied airspace.
 
-## v1 Requirements
+---
 
-Requirements for this milestone. The scaffold (~2800 lines) exists; all algorithmic kernels are missing or mocked. Every requirement below maps to one phase of implementation work.
+## Stage 2 Requirements
 
-### ESKF — Error-State Kalman Filter
+Stage 2 is a self-contained iteration. Phases are numbered 1–6 within this stage. Stage 1 work (its 36 v1 requirements + 7 phases) is archived in `.planning/archive/v1.0/` as starting capital, not as active backlog.
 
-- [ ] **ESKF-01**: 15-state ESKF implemented (δp, δv, δθ, δb_a, δb_g) with IMU prediction step (F, Q matrices, bias propagation)
-- [ ] **ESKF-02**: VO measurement update implemented (relative pose ΔR/Δt from cuVSLAM, H_vo, R_vo covariance, Kalman gain)
-- [ ] **ESKF-03**: Satellite measurement update implemented (absolute WGS84 position from matching, H_sat, R_sat from RANSAC inlier ratio)
-- [ ] **ESKF-04**: ESKF state initializes from GLOBAL_POSITION_INT at startup and on mid-flight reboot with high-uncertainty covariance
-- [ ] **ESKF-05**: Confidence tier computation outputs HIGH/MEDIUM/LOW based on covariance magnitude and last satellite correction age
-- [ ] **ESKF-06**: Coordinate transform chain implemented: pixel→camera ray (K matrix), camera→body (T_cam_body), body→NED (ESKF quaternion), NED→WGS84 — replacing all FAKE Math stubs
+The stage 1 codebase (ESKF + cuVSLAM + GPR + MAVLink + pipeline + 195 passing tests) is treated as MVP — refactoring is allowed and expected. Concept-level ideas from the parallel `try02` branch are re-implemented (not merged).
 
-### VO — Visual Odometry
+### ARCH — Hexagonal architecture & composition
 
-- [ ] **VO-01**: cuVSLAM wrapper implemented for Jetson target (Inertial mode, camera + IMU inputs, relative pose output with metric scale)
-- [ ] **VO-02**: OpenCV ORB stub conforms to the same `ISequentialVisualOdometry` interface as cuVSLAM wrapper, used on dev/CI (x86)
-- [ ] **VO-03**: TensorRT FP16 inference engine loader implemented for SuperPoint and LightGlue on Jetson; MockInferenceEngine used on dev/CI
-- [ ] **VO-04**: Scale ambiguity resolved — `scale_ambiguous` is False when ESKF provides metric scale reference; VO relative pose is metric in NED
-- [ ] **VO-05**: ImageInputPipeline batch validation minimum lowered to 1 image (not 10); `get_image_by_sequence` uses exact filename matching
+- [ ] **ARCH-01**: Codebase reorganized to `src/gps_denied/components/{vio, satellite_matcher, gpr, anchor_verifier, safety_state, flight_recorder, mavlink_io, coordinate_transforms}/`, each containing `protocol.py` + concrete implementations + (where applicable) `native/` for backend bridges
+- [ ] **ARCH-02**: Hot-path data types (`FrameState`, `IMUSample`, `PositionEstimate`, `VOEstimate`, `SatelliteAnchor`) implemented as `@dataclass(slots=True, frozen=True)` in `src/gps_denied/hot_types/`; Pydantic retained only for REST/config/DB boundary schemas
+- [ ] **ARCH-03**: Explicit DI composition root `src/gps_denied/pipeline/composition.py` exposes `build_pipeline(env: Literal["jetson", "x86_dev", "ci", "sitl"]) -> Pipeline` that wires environment-specific implementations
+- [ ] **ARCH-04**: `core/` retained for concentrated math (ESKF, factor graph, RANSAC, coordinate transforms) — these stay as pure-function single files, NOT split into `interfaces.py + types.py + impl.py`
+- [ ] **ARCH-05**: All component Protocols defined with `typing.Protocol`; concrete adapters implement them; `Pipeline` constructor takes Protocol-typed dependencies (no concrete imports inside pipeline orchestration)
+- [ ] **ARCH-06**: Per-environment YAML configuration in `config/{jetson,x86_dev,ci,sitl}.yaml`, loaded via `pydantic-settings` into a typed `RuntimeConfig` model passed to `build_pipeline`
+- [ ] **ARCH-07**: All 195 stage1 tests + 8 SITL skipped continue to pass after refactor; no regression in accuracy benchmarks
 
-### SAT — Satellite Matching
+### AC — Formal acceptance criteria document
 
-- [ ] **SAT-01**: XFeat TRT FP16 inference engine implemented for satellite feature matching on Jetson; MockInferenceEngine used on dev/CI
-- [ ] **SAT-02**: Satellite tile selection uses ESKF position ± 3σ_horizontal to define search area; tiles assembled into mosaic at matcher resolution
-- [ ] **SAT-03**: GSD normalization implemented — camera frame downsampled to match satellite GSD (0.3–0.6 m/px) before matching
-- [ ] **SAT-04**: RANSAC homography estimation produces WGS84 absolute position with confidence score from inlier ratio
-- [ ] **SAT-05**: SatelliteDataManager reads from pre-loaded GeoHash-indexed local directory (read-only, no live HTTP fetches during flight)
+- [ ] **AC-01**: `_docs/00_problem/acceptance_criteria.md` rewritten with formal AC-1.x…AC-NEW-x list adapted from `try02` and validated against this project's actual constraints
+- [ ] **AC-02**: Each AC entry includes (a) numeric thresholds, (b) validation method, (c) at least one test ID linking to `tests/`
+- [ ] **AC-03**: Position accuracy AC (50m@80%, 20m@50%, anchor age tracking, drift bounds) bound to `tests/integration/accuracy/` and `tests/e2e/`
+- [ ] **AC-04**: Failure-mode AC (visual blackout, spoofing promotion, dead reckoning, ≥3 disconnected segments) bound to `tests/blackbox/failure_modes/`
+- [ ] **AC-05**: Real-time performance AC (<400ms p95 e2e, <8GB RAM, ≥5Hz GPS_INPUT output) bound to a benchmark harness producing CI-tracked metrics
+- [ ] **AC-06**: Traceability matrix `.planning/AC-TRACEABILITY.md` generated linking every AC ID → test ID(s) → implementing component(s)
 
-### GPR — Global Place Recognition
+### SAFE — Safety anchor state machine
 
-- [ ] **GPR-01**: Real Faiss index loaded at runtime from file path (not synthetic random vectors); index built from DINOv2 descriptors of actual satellite tiles during offline pre-processing
-- [ ] **GPR-02**: DINOv2/AnyLoc TRT FP16 inference engine implemented on Jetson; MockInferenceEngine used on dev/CI
-- [ ] **GPR-03**: GPR candidate retrieval returns real tile matches ranked by descriptor similarity, used for re-localization after tracking loss
+- [ ] **SAFE-01**: `components/safety_state/SafetyAnchorStateMachine` owns authoritative `source_label ∈ {satellite_anchored, vo_extrapolated, dead_reckoned}` for every emitted `PositionEstimate`
+- [ ] **SAFE-02**: Covariance growth is monotonic in non-anchored modes; resets only on accepted satellite anchor
+- [ ] **SAFE-03**: `anchor_age_ms` recorded on every estimate; transitions to `vo_extrapolated` after configurable max-age threshold
+- [ ] **SAFE-04**: State machine receives anchor decisions from `AnchorVerifier`, never raw VPR top-K — bad candidates cannot poison the state
+- [ ] **SAFE-05**: Tile write eligibility flag exposed (`can_persist_tile: bool`) — false in `dead_reckoned` mode to prevent corrupt tile cache writes
+- [ ] **SAFE-06**: Unit tests cover all 9 state transitions; property-based test asserts covariance never decreases without an accepted anchor
 
-### MAV — MAVLink Output
+### VERIFY — Geometry-gated anchor verification
 
-- [ ] **MAV-01**: pymavlink added to dependencies; MAVLink output component implemented sending GPS_INPUT over UART at 5-10Hz
-- [ ] **MAV-02**: ESKF state and covariance mapped to GPS_INPUT fields (lat/lon/alt from position, velocity from v-state, accuracy from covariance diagonal, fix_type from confidence tier, synthesized hdop/vdop, GPS time from system clock)
-- [ ] **MAV-03**: IMU input path implemented — MAVLink listener receives ATTITUDE/RAW_IMU from flight controller at 5-10Hz and feeds ESKF prediction step
-- [ ] **MAV-04**: Consecutive-failure counter detects 3 frames without any position estimate; sends MAVLink NAMED_VALUE_FLOAT re-localization request to ground station operator
-- [ ] **MAV-05**: Telemetry output at 1Hz sends confidence score and drift estimate to ground station via MAVLink NAMED_VALUE_FLOAT
+- [ ] **VERIFY-01**: `components/anchor_verifier/GeometryGatedAnchorVerifier` accepts/rejects satellite candidate matches based on configurable gates: min inliers, max mean reprojection error (px), max homography condition number
+- [ ] **VERIFY-02**: Rejection reason string emitted on every reject (`"too_few_inliers"`, `"mre_above_threshold"`, `"degenerate_homography"`, `"freshness_expired"`)
+- [ ] **VERIFY-03**: Freshness check integrates with sector classification (active-conflict <6mo, stable-rear <12mo) — expired tiles produce `freshness_expired` reject
+- [ ] **VERIFY-04**: Verifier benchmark mode evaluates multiple matcher profiles on the same frame for offline comparison
+- [ ] **VERIFY-05**: Unit tests cover each gate independently; integration test with real Azaion frame verifies end-to-end accept/reject
 
-### PIPE — Pipeline Wiring
+### FDR — Flight data recorder
 
-- [ ] **PIPE-01**: FlightProcessor.process_frame wired end-to-end: image in → cuVSLAM VO → ESKF VO update → (keyframe) satellite match → ESKF satellite update → GPS_INPUT output
-- [ ] **PIPE-02**: SatelliteDataManager and CoordinateTransformer instantiated and wired into processor pipeline (currently standalone, not connected)
-- [ ] **PIPE-03**: FactorGraph replaced or backed by real GTSAM ISAM2 incremental smoothing with BetweenFactorPose3 (VO) and GPSFactor (satellite anchors)
-- [ ] **PIPE-04**: FailureRecoveryCoordinator connected to ESKF — on tracking loss, ESKF continues IMU-only prediction with growing uncertainty; on recovery success, ESKF is reset with satellite position
-- [ ] **PIPE-05**: ImageRotationManager integrated into process_frame — heading sweep on first frame; `calculate_precise_angle` implemented with real VO-based refinement
-- [ ] **PIPE-06**: Object GPS localization endpoint (POST /objects/locate) uses full pixel→ray→ground→WGS84 chain with ESKF attitude; hardcoded stub removed
-- [ ] **PIPE-07**: Confidence scoring and fix_type mapping wired end-to-end: ESKF confidence tier → GPS_INPUT fix_type (3/2/0), accuracy fields
-- [ ] **PIPE-08**: ImageRotationManager constructor signature fixed (accepts optional ModelManager); startup TypeError resolved
+- [ ] **FDR-01**: `components/flight_recorder/FlightRecorder` Protocol with `append_event(event)` and `export() -> FdrExportResult`
+- [ ] **FDR-02**: `InMemoryFlightRecorder` impl with bounded segments and configurable segment+storage byte limits
+- [ ] **FDR-03**: `DiskFlightRecorder` impl writing append-only JSONL segments under `data/fdr/{flight_id}/segment-NNNN.jsonl`
+- [ ] **FDR-04**: Health states `ok / degraded (≥90% storage) / critical (limit reached)` exposed via `health` property
+- [ ] **FDR-05**: Pipeline emits FDR events at every state transition, anchor decision, MAVLink send, and pipeline error
+- [ ] **FDR-06**: AC-NEW-3 forensic-thumbnail rate (≤0.1Hz on tile-generation failures) wired through FDR with size budget enforcement
 
-### TEST — Test Harness and Validation
+### VPR — Conditional + multi-scale visual place recognition
 
-- [ ] **TEST-01**: Docker SITL test harness implemented: ArduPilot SITL container, camera-replay service, satellite tile server mock, MAVLink capture
-- [ ] **TEST-02**: CI pipeline runs on x86 using OpenCV ORB stub and MockInferenceEngine; all unit tests pass
-- [ ] **TEST-03**: Accuracy validation test runs against 60-frame dataset (AD000001–AD000060.jpg) with coordinates.csv ground truth; reports 80%/50m and 60%/20m hit rates
-- [ ] **TEST-04**: Performance benchmark test validates <400ms end-to-end per frame on Jetson (or reports estimated latency breakdown on dev)
-- [ ] **TEST-05**: All 21 blackbox test scenarios (FT-P-01 to FT-P-14, FT-N-01 to FT-N-07) implemented as runnable pytest tests using SITL harness
+- [ ] **VPR-01**: VPR retrieval triggered conditionally — DINOv2 forward runs only on re-loc triggers (cold start, sharp turn AC-3.2, σ_xy > 50m, VO failure ≥2 frames, disconnected segment AC-3.3); steady-state uses geometric prior (IMU+VO predicted position) ranking by distance
+- [ ] **VPR-02**: VPR chunks decoupled from storage tiles — chunks sized to ground footprint (600-800m at deployment altitude band) with 40-50% overlap; any frame footprint falls fully inside ≥1 chunk
+- [ ] **VPR-03**: Multi-scale FAISS index — fine-scale (z=20-derived) + coarse-scale (z=17 or z=18) descriptor sets; coarse used in active-conflict sectors for change-robust retrieval
+- [ ] **VPR-04**: Dynamic top-K — K=5 in stable sectors with σ_xy ≤ 20m, K=20 in active-conflict, K=50 on expanding-window fallback
+- [ ] **VPR-05**: Chunking and indexing integrated into existing `chunk_manager.py`/`gpr.py` without breaking stage1 GPR API contracts
 
-## v2 Requirements
+### MAVOUT — MAVLink output: source labels, dual-channel scaffold
 
-Deferred to future release. Tracked but not in current roadmap.
+- [ ] **MAVOUT-01**: Every emitted `GPS_INPUT` includes `source_label`, `anchor_age_ms`, `covariance_semimajor_m` propagated from `PositionEstimate` (mapped into `horiz_accuracy` and a custom STATUSTEXT for label/age)
+- [ ] **MAVOUT-02**: `ODOMETRY` emitter scaffolded behind feature flag (`config.mavlink.odometry_enabled`); flag is false in stage 2; integration test asserts ODOMETRY is intentionally absent on the wire
+- [ ] **MAVOUT-03**: Spoofing-promotion latency monitor — listens to `GPS_RAW_INT`/`EKF_STATUS_REPORT`/`SYS_STATUS`; promotes own estimate to FC primary within <3s when real-GPS health rolling avg < threshold; emits `STATUSTEXT` on every promotion/demotion
+- [ ] **MAVOUT-04**: Visual blackout handling — pipeline switches to `dead_reckoned` within ≤1 processed frame OR ≤400ms when camera produces no usable signal; emits `VISUAL_BLACKOUT_IMU_ONLY` STATUSTEXT @ 1-2Hz
 
-### Security
+### FIXTURE — Real-flight integration fixture (Azaion 10.05.2026)
 
-- **SEC-01**: JWT bearer token authentication on all API endpoints
-- **SEC-02**: TLS 1.3 on all HTTPS connections
-- **SEC-03**: Satellite tile manifest SHA-256 integrity verification
-- **SEC-04**: Mahalanobis distance outlier rejection in ESKF measurement updates
-- **SEC-05**: CORS origins locked down (remove wildcard default)
+- [ ] **FIXTURE-01**: `tests/integration/azaion_flight/` integration test suite consuming `Data/Azaion/10.05.2026/` (tlog + cropped EO video + MAVLink CSV)
+- [ ] **FIXTURE-02**: Preprocessing script `scripts/prep_azaion_fixture.py` producing — (a) HUD-stripped EO frames at 0.7 fps, (b) IMU/GPS/ATTITUDE CSV from tlog, (c) timestamp-aligned manifest
+- [ ] **FIXTURE-03**: MAVLink replay test — feed tlog through `MAVLinkBridge` parser, assert all `GLOBAL_POSITION_INT`/`RAW_IMU`/`ATTITUDE` messages decoded without error
+- [ ] **FIXTURE-04**: ESKF real-IMU smoke test — replay IMU samples through `ESKFCore.predict`, assert no NaN/Inf, bounded covariance growth
+- [ ] **FIXTURE-05**: VO smoke test on cropped EO frames using ORB-SLAM3 backend — assert ≥30% frame registration success
+- [ ] **FIXTURE-06**: GPS-denial simulation — mask `GPS_RAW_INT` for t∈[180s, 280s], replay rest of stream, assert pipeline switches to `vo_extrapolated` and back to `satellite_anchored` correctly
+- [ ] **FIXTURE-07**: Azaion fixture documented in `_docs/00_problem/fixtures.md` with ground-truth references and known limitations (low altitude, multirotor dynamics, HUD overlay)
 
-### Operational
+### TEST — Test taxonomy & infrastructure
 
-- **OPS-01**: Uvicorn `reload` flag defaults to False in production config
-- **OPS-02**: Structured logging with configurable log levels per module
-- **OPS-03**: Pre-flight health check validates TRT engines loaded, tiles present, IMU receiving
-- **OPS-04**: ResultManager.publish_waypoint_update implemented for waypoint SSE emission
+- [ ] **TEST-01**: `tests/` reorganized to `tests/{unit,integration,blackbox,sitl,e2e}/`; existing tests redistributed by category
+- [ ] **TEST-02**: `pyproject.toml` test markers updated — `pytest -m unit` / `-m integration` / etc.; CI runs unit+integration on every push, blackbox on PR, sitl+e2e nightly
+- [ ] **TEST-03**: AC traceability auto-generated — pytest plugin tags each test with `@pytest.mark.ac("AC-1.1")`; `scripts/gen_ac_traceability.py` produces the matrix in `.planning/AC-TRACEABILITY.md`
 
-### Performance
+### OBS — Observability & tooling
 
-- **PERF-01**: Dual CUDA stream execution (Stream A: VO, Stream B: satellite matching) for pipeline parallelism
-- **PERF-02**: Satellite tile RAM preload (±2km corridor) at startup for sub-millisecond tile access
+- [ ] **OBS-01**: Structured JSON logging via `structlog` with `correlation_id` (frame_id) propagated through pipeline; Pydantic logging schemas at boundaries
+- [ ] **OBS-02**: CLI tool `gps_denied` (typer-based) with subcommands — `replay --tlog ... --video ...`, `benchmark --scenario ...`, `bench-ac AC-1.1` for AC-driven benchmark runs
+- [ ] **OBS-03**: Per-environment Docker images split — `Dockerfile.x86_dev` for CI/dev, `Dockerfile.jetson` (multi-stage with TRT engine prebuild step) for hardware
 
-## Out of Scope
+---
 
-Explicitly excluded. Documented to prevent scope creep.
+## Stage 3 candidates (parking lot)
 
-| Feature | Reason |
-|---------|--------|
-| TRT engine building tooling | Engines are pre-built offline via trtexec; system only loads them |
-| Google Maps tile download tooling | Tiles pre-cached before flight; no live internet during flight |
-| Full ArduPilot hardware validation on Jetson | Post-v1; Jetson hardware testing is not in scope for this milestone |
-| Mobile/web ground station UI | SSE stream consumed by external systems; UI is out of scope |
-| Multi-UAV coordination | Single UAV instance only |
-| GTSAM ARM64 source build tooling | GTSAM on Jetson requires source compilation; CI uses mock; Jetson build is ops concern |
-| tech_stack.md synchronization | Documented inconsistency (3fps vs 0.7fps, etc.); separate documentation task |
+- Mid-flight tile generation + write-back to Azaion Satellite Service (AC-8.4)
+- On-device hardware validation on Jetson Orin Nano Super
+- Dual-channel MAVLink ODOMETRY enabled (depends on ArduPilot fixes for EKF3 source switching)
+- AC-NEW-1 cold-boot time-to-first-fix bench (<30s, 50× cold reboot)
+- BASALT VIO backend evaluation (only if cuVSLAM hits a blocker)
+
+## Out of Scope (Stage 2)
+
+- Migration to PostgreSQL (SQLite remains embedded default; Postgres optional for ground station only)
+- Folder-per-component layout for `core/` math files (ESKF/factor graph stay concentrated)
+- Real microservices with separate processes / IPC
+- Pydantic on per-frame hot path (dataclasses replace it)
+- Mobile/web ground station UI
+- Multi-UAV coordination
 
 ## Traceability
 
-Which phases cover which requirements. Populated from ROADMAP.md phase assignments.
+Populated by roadmapper on 2026-05-10. Test IDs will be filled in by `/gsd:plan-phase` and `/gsd:implement` as each phase produces concrete tests.
 
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| ESKF-01 | Phase 1 | Pending |
-| ESKF-02 | Phase 1 | Pending |
-| ESKF-03 | Phase 1 | Pending |
-| ESKF-04 | Phase 1 | Pending |
-| ESKF-05 | Phase 1 | Pending |
-| ESKF-06 | Phase 1 | Pending |
-| VO-01 | Phase 2 | Pending |
-| VO-02 | Phase 2 | Pending |
-| VO-03 | Phase 2 | Pending |
-| VO-04 | Phase 2 | Pending |
-| VO-05 | Phase 2 | Pending |
-| SAT-01 | Phase 3 | Pending |
-| SAT-02 | Phase 3 | Pending |
-| SAT-03 | Phase 3 | Pending |
-| SAT-04 | Phase 3 | Pending |
-| SAT-05 | Phase 3 | Pending |
-| GPR-01 | Phase 3 | Pending |
-| GPR-02 | Phase 3 | Pending |
-| GPR-03 | Phase 3 | Pending |
-| MAV-01 | Phase 4 | Pending |
-| MAV-02 | Phase 4 | Pending |
-| MAV-03 | Phase 4 | Pending |
-| MAV-04 | Phase 4 | Pending |
-| MAV-05 | Phase 4 | Pending |
-| PIPE-01 | Phase 5 | Pending |
-| PIPE-02 | Phase 5 | Pending |
-| PIPE-03 | Phase 5 | Pending |
-| PIPE-04 | Phase 5 | Pending |
-| PIPE-05 | Phase 5 | Pending |
-| PIPE-06 | Phase 5 | Pending |
-| PIPE-07 | Phase 5 | Pending |
-| PIPE-08 | Phase 5 | Pending |
-| TEST-01 | Phase 6 | Pending |
-| TEST-02 | Phase 6 | Pending |
-| TEST-03 | Phase 7 | Pending |
-| TEST-04 | Phase 7 | Pending |
-| TEST-05 | Phase 7 | Pending |
+| REQ | Phase | Tests |
+|-----|-------|-------|
+| ARCH-01 | Phase 1 | _pending plan-phase_ |
+| ARCH-02 | Phase 1 | _pending plan-phase_ |
+| ARCH-03 | Phase 1 | _pending plan-phase_ |
+| ARCH-04 | Phase 1 | _pending plan-phase_ |
+| ARCH-05 | Phase 1 | _pending plan-phase_ |
+| ARCH-06 | Phase 1 | _pending plan-phase_ |
+| ARCH-07 | Phase 1 | _pending plan-phase_ |
+| AC-01 | Phase 2 | _pending plan-phase_ |
+| AC-02 | Phase 2 | _pending plan-phase_ |
+| AC-03 | Phase 2 | _pending plan-phase_ |
+| AC-04 | Phase 2 | _pending plan-phase_ |
+| AC-05 | Phase 2 | _pending plan-phase_ |
+| AC-06 | Phase 2 | _pending plan-phase_ |
+| TEST-01 | Phase 2 | _pending plan-phase_ |
+| TEST-02 | Phase 2 | _pending plan-phase_ |
+| TEST-03 | Phase 2 | _pending plan-phase_ |
+| OBS-01 | Phase 2 | _pending plan-phase_ |
+| SAFE-01 | Phase 3 | _pending plan-phase_ |
+| SAFE-02 | Phase 3 | _pending plan-phase_ |
+| SAFE-03 | Phase 3 | _pending plan-phase_ |
+| SAFE-04 | Phase 3 | _pending plan-phase_ |
+| SAFE-05 | Phase 3 | _pending plan-phase_ |
+| SAFE-06 | Phase 3 | _pending plan-phase_ |
+| VERIFY-01 | Phase 3 | _pending plan-phase_ |
+| VERIFY-02 | Phase 3 | _pending plan-phase_ |
+| VERIFY-03 | Phase 3 | _pending plan-phase_ |
+| VERIFY-04 | Phase 3 | _pending plan-phase_ |
+| VERIFY-05 | Phase 3 | _pending plan-phase_ |
+| VPR-01 | Phase 4 | _pending plan-phase_ |
+| VPR-02 | Phase 4 | _pending plan-phase_ |
+| VPR-03 | Phase 4 | _pending plan-phase_ |
+| VPR-04 | Phase 4 | _pending plan-phase_ |
+| VPR-05 | Phase 4 | _pending plan-phase_ |
+| FDR-01 | Phase 4 | _pending plan-phase_ |
+| FDR-02 | Phase 4 | _pending plan-phase_ |
+| FDR-03 | Phase 4 | _pending plan-phase_ |
+| FDR-04 | Phase 4 | _pending plan-phase_ |
+| FDR-05 | Phase 4 | _pending plan-phase_ |
+| FDR-06 | Phase 4 | _pending plan-phase_ |
+| MAVOUT-01 | Phase 5 | _pending plan-phase_ |
+| MAVOUT-02 | Phase 5 | _pending plan-phase_ |
+| MAVOUT-03 | Phase 5 | _pending plan-phase_ |
+| MAVOUT-04 | Phase 5 | _pending plan-phase_ |
+| FIXTURE-01 | Phase 6 | _pending plan-phase_ |
+| FIXTURE-02 | Phase 6 | _pending plan-phase_ |
+| FIXTURE-03 | Phase 6 | _pending plan-phase_ |
+| FIXTURE-04 | Phase 6 | _pending plan-phase_ |
+| FIXTURE-05 | Phase 6 | _pending plan-phase_ |
+| FIXTURE-06 | Phase 6 | _pending plan-phase_ |
+| FIXTURE-07 | Phase 6 | _pending plan-phase_ |
+| OBS-02 | Phase 6 | _pending plan-phase_ |
+| OBS-03 | Phase 6 | _pending plan-phase_ |
 
-**Coverage:**
-- v1 requirements: 36 total
-- Mapped to phases: 36
-- Unmapped: 0
-
----
-*Requirements defined: 2026-04-01*
-*Last updated: 2026-04-01 after initial definition*
+**Coverage:** 52/52 requirements mapped. No orphans, no duplicates.

.planning/ROADMAP.md

@@ -1,114 +1,152 @@
-# Roadmap: GPS-Denied Onboard Navigation System
+# Roadmap: GPS-Denied Onboard Navigation System — Stage 2
+
+**Stage:** 2 (independent iteration)
+**Created:** 2026-05-10
+**Branch:** `stage2` (HEAD = stage1; v1.0 archived under `.planning/archive/v1.0/`)
+**Granularity:** standard
+**Total phases:** 6
+**Total requirements mapped:** 52 / 52 (100% coverage)
+
+---
 
 ## Overview
 
-The scaffold exists (~2800 lines): FastAPI service, all component ABCs, Pydantic schemas, database layer, and SSE streaming are in place. What is missing is every algorithmic kernel. This roadmap implements them in dependency order: the ESKF math core first (everything else feeds into it), then the two sensor inputs (VO and satellite/GPR), then the MAVLink output that closes the loop to the flight controller, then end-to-end pipeline wiring, then a Docker SITL test harness, and finally accuracy validation against real flight data.
+Stage 2 is a **self-contained iteration** with its own phase numbering (1–6). It is NOT a continuation of Stage 1's seven phases — those are archived under `.planning/archive/v1.0/` and treated as MVP starting capital (the working ESKF + cuVSLAM/ORB VO + GPR + MAVLink + 195 passing tests).
+
+The Stage 2 mission: refactor the inherited MVP into a hexagonal/ports-and-adapters architecture, re-implement (not merge) selected concept-level ideas from the parallel `try02` branch, formalize acceptance criteria with testable numerics, and add the Azaion 10.05.2026 real-flight integration fixture — all without regressing any of the 195 stage1 tests.
+
+Phases are derived from the ten Stage 2 requirement categories (ARCH, AC, SAFE, VERIFY, FDR, VPR, MAVOUT, FIXTURE, TEST, OBS) and ordered so each phase stabilizes the Protocol surfaces and test infrastructure that the next phase depends on.
+
+## Phase Dependency Order
+
+```
+Phase 1 (ARCH — hexagonal refactor + composition root; Protocols stabilized)
+   ↓
+Phase 2 (AC + TEST taxonomy + structlog spine — measurement scaffolding)
+   ↓
+Phase 3 (SAFE state machine + VERIFY anchor gates — authoritative source labels)
+   ↓
+Phase 4 (Conditional Multi-Scale VPR + FDR — uses SAFE triggers, FDR for audit)
+   ↓
+Phase 5 (MAVOUT — source-aware GPS_INPUT + spoofing + blackout — needs SAFE labels)
+   ↓
+Phase 6 (FIXTURE — Azaion replay + CLI + per-env Docker — exercises everything e2e)
+```
 
 ## Phases
 
-- [ ] **Phase 1: ESKF Core** - 15-state error-state Kalman filter, coordinate transforms, confidence scoring
-- [ ] **Phase 2: Visual Odometry** - cuVSLAM wrapper (Jetson) + OpenCV ORB stub (dev/CI) + TRT SuperPoint/LightGlue
-- [ ] **Phase 3: Satellite Matching + GPR** - XFeat TRT matching, offline tile pipeline, real Faiss GPR index
-- [ ] **Phase 4: MAVLink I/O** - pymavlink GPS_INPUT output loop, IMU input listener, telemetry, re-localization request
-- [ ] **Phase 5: End-to-End Pipeline Wiring** - processor integration, GTSAM factor graph, recovery coordinator, object localization
-- [ ] **Phase 6: Docker SITL Harness + CI** - ArduPilot SITL, camera replay, tile server mock, CI integration
-- [ ] **Phase 7: Accuracy Validation** - 60-frame dataset validation, latency profiling, blackbox test suite
+- [ ] **Phase 1: Hexagonal Refactor & Composition Root** — Reorganize stage1 MVP into `components/` hexagonal layout with Protocol-typed DI composition root; no regressions.
+- [ ] **Phase 2: Acceptance Criteria + Test Taxonomy + Observability Spine** — Formal AC document with numeric thresholds, `tests/{unit,integration,blackbox,sitl,e2e}/` taxonomy, structlog correlation_id spine.
+- [ ] **Phase 3: Safety Anchor State Machine & Geometry-Gated Verifier** — Authoritative `source_label` ownership + accept/reject gates for satellite anchors before they reach ESKF.
+- [ ] **Phase 4: Conditional Multi-Scale VPR + Flight Data Recorder** — Trigger-driven DINOv2 forward, multi-scale FAISS chunks, append-only event log with bounded storage.
+- [ ] **Phase 5: MAVLink Source-Aware Output & Spoofing/Blackout Handling** — Source labels + anchor age in GPS_INPUT, spoofing-promotion <3s, visual-blackout dead-reckoning ≤400ms, ODOMETRY scaffold behind feature flag.
+- [ ] **Phase 6: Real-Flight Fixture (Azaion 10.05.2026) + CLI + Per-Env Docker** — End-to-end integration test on real flight data, `gps_denied` typer CLI, split Jetson/x86 Dockerfiles.
 
 ## Phase Details
 
-### Phase 1: ESKF Core
-**Goal**: A correct, standalone ESKF implementation exists that fuses IMU, VO, and satellite measurements and outputs confidence-tiered position estimates in WGS84
-**Depends on**: Nothing (first phase — no other algorithmic component depends on this being absent)
-**Requirements**: ESKF-01, ESKF-02, ESKF-03, ESKF-04, ESKF-05, ESKF-06
-**Success Criteria** (what must be TRUE):
-  1. ESKF propagates nominal state (position, velocity, quaternion, biases) from synthetic IMU inputs and covariance grows correctly between measurement updates
-  2. VO measurement update reduces position uncertainty and innovation is within expected bounds for a simulated relative pose input
-  3. Satellite measurement update corrects absolute position and covariance tightens to satellite noise level
-  4. Confidence tier outputs HIGH when last satellite correction is recent and covariance is small, MEDIUM on VO-only, LOW on IMU-only — verified by unit tests
-  5. Full coordinate chain (pixel → camera ray → body → NED → WGS84) produces correct GPS coordinates for a known geometry test case; all FAKE Math stubs replaced
-**Plans**: 3 plans
-Plans:
-- [x] 01-01-PLAN.md — ESKF core algorithm (schemas, 15-state filter, IMU prediction, VO/satellite updates, confidence tiers)
-- [x] 01-02-PLAN.md — Coordinate chain fix (replace fake math with real K matrix projection, ray-ground intersection)
-- [x] 01-03-PLAN.md — Unit tests for ESKF and coordinate chain (18+ ESKF tests, 10+ coordinate tests)
+### Phase 1: Hexagonal Refactor & Composition Root
 
-### Phase 2: Visual Odometry
-**Goal**: VO produces metric relative poses via cuVSLAM on Jetson and via OpenCV ORB on dev/CI, both satisfying the same interface — no more scale-ambiguous unit vectors
-**Depends on**: Phase 1 (ESKF provides metric scale reference and coordinate transforms for VO measurement update)
-**Requirements**: VO-01, VO-02, VO-03, VO-04, VO-05
+**Goal**: Stage1 MVP reorganized into hexagonal/ports-and-adapters layout with explicit DI composition root; all 195 stage1 tests still pass.
+**Depends on**: Nothing (first phase; consumes stage1 archived code as input).
+**Requirements**: ARCH-01, ARCH-02, ARCH-03, ARCH-04, ARCH-05, ARCH-06, ARCH-07
 **Success Criteria** (what must be TRUE):
-  1. cuVSLAM wrapper initializes in Inertial mode with camera intrinsics and IMU parameters, and returns RelativePose with `scale_ambiguous=False` and metric translation in NED
-  2. OpenCV ORB stub satisfies the same ISequentialVisualOdometry interface and passes the same interface contract tests as the cuVSLAM wrapper
-  3. TRT SuperPoint/LightGlue engines load and run inference on Jetson; MockInferenceEngine is selected automatically on dev/x86
-  4. ImageInputPipeline accepts single-image batches without error; sequence lookup returns the correct frame with no substring collision
+  1. Every swappable component (vio, satellite_matcher, gpr, anchor_verifier, safety_state, flight_recorder, mavlink_io, coordinate_transforms) lives under `src/gps_denied/components/<name>/` with its own `protocol.py` + concrete impls + (where needed) `native/` bridge.
+  2. Hot-path types (`FrameState`, `IMUSample`, `PositionEstimate`, `VOEstimate`, `SatelliteAnchor`) are `@dataclass(slots=True, frozen=True)` and Pydantic no longer touches the per-frame path.
+  3. Calling `build_pipeline(env="x86_dev")` / `"jetson"` / `"ci"` / `"sitl"` from `pipeline/composition.py` returns a fully-wired `Pipeline` with environment-correct adapters and no concrete imports leaking into pipeline orchestration.
+  4. Per-environment YAML configs (`config/{jetson,x86_dev,ci,sitl}.yaml`) load via `pydantic-settings` into a typed `RuntimeConfig` that drives composition.
+  5. `pytest` runs all 195 stage1 tests (+ 8 SITL skipped) green and accuracy benchmarks show no regression vs the archived stage1 baseline.
 **Plans**: TBD
 
-### Phase 3: Satellite Matching + GPR
-**Goal**: The system can correct absolute position from pre-loaded satellite tiles and re-localize after tracking loss using a real Faiss descriptor index
-**Depends on**: Phase 1 (ESKF position uncertainty drives tile selection radius and measurement update), Phase 2 (VO provides keyframe selection timing)
-**Requirements**: SAT-01, SAT-02, SAT-03, SAT-04, SAT-05, GPR-01, GPR-02, GPR-03
+### Phase 2: Acceptance Criteria + Test Taxonomy + Observability Spine
+
+**Goal**: Project gains a formal, testable acceptance-criteria contract, a structured test taxonomy, and a structured-logging spine — the measurement scaffolding every later phase needs to prove its claims.
+**Depends on**: Phase 1 (Protocol surfaces and components/ layout must exist before tests/AC can reference them).
+**Requirements**: AC-01, AC-02, AC-03, AC-04, AC-05, AC-06, TEST-01, TEST-02, TEST-03, OBS-01
 **Success Criteria** (what must be TRUE):
-  1. Satellite tile selection queries the local GeoHash-indexed directory using ESKF position ± 3σ and returns correct tiles without any HTTP requests
-  2. Camera frame is GSD-normalized to satellite resolution before matching; XFeat TRT inference runs on Jetson and MockInferenceEngine on dev/CI
-  3. RANSAC homography produces a WGS84 position estimate with a confidence score derived from inlier ratio, accepted by ESKF satellite measurement update
-  4. GPR loads a real Faiss index from disk and returns tile candidates ranked by DINOv2 descriptor similarity (not random vectors)
-  5. After simulated tracking loss, GPR candidate + MetricRefinement produces an ESKF re-localization within expected accuracy bounds
+  1. `_docs/00_problem/acceptance_criteria.md` lists every AC-1.x…AC-NEW-x with numeric threshold + validation method + linked test ID(s); no AC entry is unbound.
+  2. `tests/` is reorganized into `unit/integration/blackbox/sitl/e2e/`, every existing test is reclassified, and `pytest -m unit|integration|blackbox|sitl|e2e` selects the right subset for CI.
+  3. Running `scripts/gen_ac_traceability.py` produces `.planning/AC-TRACEABILITY.md` linking every AC ID → test ID(s) → component(s); CI fails if any AC is orphaned.
+  4. Position-accuracy, failure-mode, and real-time-performance ACs are wired to `tests/integration/accuracy/`, `tests/blackbox/failure_modes/`, and a benchmark harness that emits CI-tracked metrics.
+  5. Pipeline emits structured JSON via `structlog` with `correlation_id` (frame_id) on every per-frame log line, and Pydantic logging schemas guard the boundary records.
 **Plans**: TBD
 
-### Phase 4: MAVLink I/O
-**Goal**: The flight controller receives GPS_INPUT at 5-10Hz and the system receives IMU data from the flight controller — the primary acceptance criterion is met end-to-end for the communication layer
-**Depends on**: Phase 1 (ESKF state is the source for GPS_INPUT field population; IMU data drives ESKF prediction)
-**Requirements**: MAV-01, MAV-02, MAV-03, MAV-04, MAV-05
+### Phase 3: Safety Anchor State Machine & Geometry-Gated Verifier
+
+**Goal**: A separate safety layer — not the ESKF — owns the authoritative `source_label`, enforces monotonic covariance growth in non-anchored modes, and only accepts satellite anchors that pass formal geometric gates.
+**Depends on**: Phase 2 (needs AC document + test taxonomy + structlog so state-machine behavior is testable and observable).
+**Requirements**: SAFE-01, SAFE-02, SAFE-03, SAFE-04, SAFE-05, SAFE-06, VERIFY-01, VERIFY-02, VERIFY-03, VERIFY-04, VERIFY-05
 **Success Criteria** (what must be TRUE):
-  1. pymavlink sends GPS_INPUT messages to a MAVLink endpoint at 5-10Hz; all required fields populated (lat, lon, alt, velocity, accuracy, fix_type, hdop, vdop, GPS time)
-  2. fix_type maps correctly from ESKF confidence tier: HIGH → 3 (3D fix), MEDIUM → 2 (2D fix), LOW → 0 (no fix)
-  3. IMU listener receives ATTITUDE/RAW_IMU from flight controller at 5-10Hz and ESKF prediction step runs at that rate between camera frames
-  4. After 3 consecutive frames with no position estimate, a MAVLink NAMED_VALUE_FLOAT message with last known position is sent (verifiable in SITL logs)
-  5. Telemetry at 1Hz emits confidence score and drift estimate to ground station via NAMED_VALUE_FLOAT
+  1. Every emitted `PositionEstimate` carries one of `satellite_anchored / vo_extrapolated / dead_reckoned` set by `SafetyAnchorStateMachine`, plus an `anchor_age_ms` field that increases until the next accepted anchor.
+  2. Property-based tests prove covariance never decreases without an accepted anchor, and a unit-test matrix exercises all 9 declared state transitions.
+  3. `GeometryGatedAnchorVerifier` accepts/rejects each candidate using configurable gates (min inliers, max mean reprojection error, max homography condition number, freshness window) and emits a machine-readable rejection reason on every reject.
+  4. Tile-write eligibility (`can_persist_tile`) is exposed by the state machine and is `false` whenever the system is in `dead_reckoned`, so the tile cache cannot be poisoned during blind flight.
+  5. The state machine never sees raw VPR top-K candidates — `AnchorVerifier` is the only path that can hand it an accepted anchor — and benchmark mode lets matcher profiles be compared offline on a fixed frame.
 **Plans**: TBD
 
-### Phase 5: End-to-End Pipeline Wiring
-**Goal**: A single uploaded camera frame travels through the full pipeline — VO, ESKF update, satellite correction (on keyframes), GPS_INPUT output — with no hardcoded stubs in the path
-**Depends on**: Phase 1, Phase 2, Phase 3, Phase 4 (all algorithmic components must exist to be wired)
-**Requirements**: PIPE-01, PIPE-02, PIPE-03, PIPE-04, PIPE-05, PIPE-06, PIPE-07, PIPE-08
+### Phase 4: Conditional Multi-Scale VPR + Flight Data Recorder
+
+**Goal**: DINOv2 retrieval runs only when re-localization is actually needed; chunks are decoupled from storage tiles with multi-scale coverage; every state transition / anchor decision / MAVLink emission is captured in an append-only flight recorder with bounded storage and explicit health states.
+**Depends on**: Phase 3 (VPR triggers and FDR events ride on SAFE state-transitions and VERIFY accept/reject decisions).
+**Requirements**: VPR-01, VPR-02, VPR-03, VPR-04, VPR-05, FDR-01, FDR-02, FDR-03, FDR-04, FDR-05, FDR-06
 **Success Criteria** (what must be TRUE):
-  1. process_frame executes the full chain without error: VO relative pose → ESKF VO update → (every 5-10 frames) satellite match → ESKF satellite update → GPS_INPUT sent to flight controller
-  2. SatelliteDataManager and CoordinateTransformer are instantiated in app.py lifespan and injected into the processor; no component is standalone
-  3. FactorGraphOptimizer calls real GTSAM ISAM2 update when GTSAM is available; mock path remains for CI
-  4. Object GPS localization (POST /objects/locate) returns a WGS84 position using the real pixel→ray→ground chain; hardcoded (48.0, 37.0) stub is gone
-  5. Application starts without TypeError; ImageRotationManager constructor accepts the model manager argument
+  1. In steady state the pipeline ranks chunks by IMU+VO geometric prior and skips the DINOv2 forward; DINOv2 runs only on declared re-loc triggers (cold start, sharp turn, σ_xy > 50m, VO failure ≥2 frames, disconnected segment).
+  2. VPR chunks cover the operating area with 600–800m ground footprint and 40–50% overlap so any frame footprint falls fully inside ≥1 chunk; FAISS holds both fine-scale (z=20) and coarse-scale (z=17/18) descriptor sets.
+  3. Top-K is dynamic — K=5 stable, K=20 active-conflict, K=50 expanding-window — and the integration uses the existing `chunk_manager.py` / `gpr.py` API surface without breaking stage1 GPR contracts.
+  4. `FlightRecorder` writes append-only JSONL segments to `data/fdr/{flight_id}/segment-NNNN.jsonl`, enforces configurable segment + total storage byte limits, and exposes `health ∈ {ok, degraded, critical}`.
+  5. State transitions, anchor accept/reject decisions, MAVLink sends, and pipeline errors are all recorded as FDR events; AC-NEW-3 forensic thumbnails fire at ≤0.1Hz on tile-generation failures within the FDR size budget.
 **Plans**: TBD
 
-### Phase 6: Docker SITL Harness + CI
-**Goal**: The full pipeline can be tested in a reproducible Docker environment with ArduPilot SITL, camera replay, and a tile server mock — and CI runs this on every commit
-**Depends on**: Phase 5 (all components must be wired before integration testing is meaningful)
-**Requirements**: TEST-01, TEST-02
+### Phase 5: MAVLink Source-Aware Output & Spoofing/Blackout Handling
+
+**Goal**: The MAVLink output the flight controller actually sees carries source provenance and reacts correctly to GPS spoofing and visual blackout, with the dual-channel ODOMETRY path scaffolded but disabled.
+**Depends on**: Phase 4 (needs SAFE source labels, FDR audit channel, and VPR triggers to drive blackout/promotion semantics).
+**Requirements**: MAVOUT-01, MAVOUT-02, MAVOUT-03, MAVOUT-04
 **Success Criteria** (what must be TRUE):
-  1. `docker compose up` starts ArduPilot SITL, the GPS-denied service, a camera-replay container, and a satellite tile server mock — all communicate over MAVLink and HTTP
-  2. CI pipeline runs on x86 using OpenCV ORB stub and MockInferenceEngine; all 85+ unit tests pass with no manual steps
-  3. MAVLink GPS_INPUT messages are captured in SITL logs and show 5-10Hz output rate during camera replay
-  4. Tracking loss scenario (simulated by replaying frames with no overlap) triggers RECOVERY state and sends re-localization request
+  1. Every `GPS_INPUT` message carries `source_label`, `anchor_age_ms`, and `covariance_semimajor_m` propagated from the corresponding `PositionEstimate` (mapped into `horiz_accuracy` and a custom STATUSTEXT for label/age).
+  2. When real-GPS health rolling average drops below threshold, the system promotes its own estimate to FC primary within <3s and emits a `STATUSTEXT` on every promotion/demotion.
+  3. When the camera produces no usable signal, the pipeline switches to `dead_reckoned` within ≤1 processed frame OR ≤400ms and emits `VISUAL_BLACKOUT_IMU_ONLY` STATUSTEXT at 1–2Hz until imagery returns.
+  4. The `ODOMETRY` emitter exists in code but is disabled by `config.mavlink.odometry_enabled=false` in stage 2, and an integration test asserts ODOMETRY is intentionally absent on the wire.
 **Plans**: TBD
 
-### Phase 7: Accuracy Validation
-**Goal**: The system demonstrably meets the navigation accuracy acceptance criteria on the 60-frame test dataset, and all 21 blackbox test scenarios are implemented as runnable tests
-**Depends on**: Phase 6 (SITL harness is required for the blackbox test scenarios)
-**Requirements**: TEST-03, TEST-04, TEST-05
+### Phase 6: Real-Flight Fixture (Azaion 10.05.2026) + CLI + Per-Env Docker
+
+**Goal**: The whole stack is exercised end-to-end against real flight data, an operator-facing CLI replays flights and runs AC benchmarks, and per-environment Docker images close the deployment loop.
+**Depends on**: Phase 5 (final phase — exercises ARCH + AC + SAFE + VERIFY + VPR + FDR + MAVOUT against the Azaion fixture).
+**Requirements**: FIXTURE-01, FIXTURE-02, FIXTURE-03, FIXTURE-04, FIXTURE-05, FIXTURE-06, FIXTURE-07, OBS-02, OBS-03
 **Success Criteria** (what must be TRUE):
-  1. Running against AD000001–AD000060.jpg with coordinates.csv ground truth: 80% of frames within 50m error and 60% of frames within 20m error
-  2. Maximum cumulative VO drift between satellite corrections is less than 100m across any segment in the test dataset
-  3. End-to-end latency per frame (camera capture to GPS_INPUT) is under 400ms on Jetson, with a breakdown report per pipeline stage
-  4. All 21 blackbox test scenarios (FT-P-01 to FT-P-14, FT-N-01 to FT-N-07) run as pytest tests against the SITL harness and produce a pass/fail report
+  1. `tests/integration/azaion_flight/` runs against `Data/Azaion/10.05.2026/` (tlog + cropped EO video + MAVLink CSV) and is documented in `_docs/00_problem/fixtures.md` with ground-truth references and known limitations.
+  2. `scripts/prep_azaion_fixture.py` produces HUD-stripped EO frames at 0.7 fps, an IMU/GPS/ATTITUDE CSV from the tlog, and a timestamp-aligned manifest.
+  3. MAVLink replay decodes every `GLOBAL_POSITION_INT` / `RAW_IMU` / `ATTITUDE` message without error; ESKF replay on the real IMU samples produces no NaN/Inf and shows bounded covariance growth; ORB-SLAM3 VO smoke test achieves ≥30% frame registration on the cropped EO frames.
+  4. The GPS-denial simulation masks `GPS_RAW_INT` for t∈[180s, 280s] and the pipeline correctly switches to `vo_extrapolated` and back to `satellite_anchored` when GPS returns.
+  5. `gps_denied` typer CLI exposes `replay --tlog ... --video ...`, `benchmark --scenario ...`, and `bench-ac AC-1.1`; `Dockerfile.x86_dev` and `Dockerfile.jetson` (multi-stage with TRT engine prebuild step) build green and run the replay end-to-end on their respective platforms.
 **Plans**: TBD
 
 ## Progress
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. ESKF Core | 0/3 | Planned | - |
-| 2. Visual Odometry | 0/TBD | Not started | - |
-| 3. Satellite Matching + GPR | 0/TBD | Not started | - |
-| 4. MAVLink I/O | 0/TBD | Not started | - |
-| 5. End-to-End Pipeline Wiring | 0/TBD | Not started | - |
-| 6. Docker SITL Harness + CI | 0/TBD | Not started | - |
-| 7. Accuracy Validation | 0/TBD | Not started | - |
+| 1. Hexagonal Refactor & Composition Root | 0/0 | Not started | - |
+| 2. Acceptance Criteria + Test Taxonomy + Observability Spine | 0/0 | Not started | - |
+| 3. Safety Anchor State Machine & Geometry-Gated Verifier | 0/0 | Not started | - |
+| 4. Conditional Multi-Scale VPR + Flight Data Recorder | 0/0 | Not started | - |
+| 5. MAVLink Source-Aware Output & Spoofing/Blackout Handling | 0/0 | Not started | - |
+| 6. Real-Flight Fixture (Azaion 10.05.2026) + CLI + Per-Env Docker | 0/0 | Not started | - |
+
+## Coverage Summary
+
+| Category | Count | Phase |
+|----------|-------|-------|
+| ARCH | 7 | Phase 1 |
+| AC | 6 | Phase 2 |
+| TEST | 3 | Phase 2 |
+| OBS-01 | 1 | Phase 2 |
+| SAFE | 6 | Phase 3 |
+| VERIFY | 5 | Phase 3 |
+| VPR | 5 | Phase 4 |
+| FDR | 6 | Phase 4 |
+| MAVOUT | 4 | Phase 5 |
+| FIXTURE | 7 | Phase 6 |
+| OBS-02, OBS-03 | 2 | Phase 6 |
+| **Total** | **52** | **6 phases** |
+
+100% of Stage 2 requirements mapped; no orphans; no duplicates.

.planning/STATE.md

@@ -1,71 +1,98 @@
 ---
 gsd_state_version: 1.0
-milestone: v1.0
-milestone_name: milestone
-status: Phase 1 complete
-last_updated: "2026-04-01T21:05:00Z"
+milestone: v2.0
+milestone_name: Stage 2 — Hexagonal architecture + try02 idea integration + real-flight fixture
+status: phase_1_complete
+last_updated: "2026-05-11T00:00:00Z"
+last_activity: 2026-05-11 — Phase 1 complete; 01-08 composition root + YAML config shipped; 216/216 tests green
 progress:
-  total_phases: 7
+  total_phases: 6
   completed_phases: 1
-  total_plans: 3
-  completed_plans: 3
+  total_plans: 8
+  completed_plans: 8
+  percent: 100
 ---
 
 # Project State
 
 ## Project Reference
 
-See: .planning/PROJECT.md (updated 2026-04-01)
+See: .planning/PROJECT.md (updated 2026-05-10)
 
 **Core value:** Flight controller must receive valid MAVLink GPS_INPUT at 5-10Hz with position accuracy ≤50m for 80% of frames — without this, the UAV cannot navigate in GPS-denied airspace.
-**Current focus:** Phase 2 — Visual Odometry Pipeline
+**Current focus:** Stage 2 / Phase 1 — Hexagonal Refactor & Composition Root
 
 ## Current Phase
 
-**Phase:** 1 — ESKF Core (✓ Complete)
-**Next action:** Run `/gsd:plan-phase 2` to plan Phase 2 (Visual Odometry Pipeline)
+**Phase:** 1 — Hexagonal Refactor & Composition Root (COMPLETE)
+**Next phase:** Phase 2 — Acceptance Criteria + Test Taxonomy + Observability Spine
 
 ## Roadmap Summary
 
+### Stage 1 (v1.0 — archived under `.planning/archive/v1.0/`)
+
+Treated as MVP starting capital, not active backlog. ESKF + cuVSLAM/ORB VO + GPR + MAVLink + 195 passing tests + 8 SITL skipped. Refactoring is allowed and expected.
+
+### Stage 2 (v2.0 — current iteration, Phases 1–6)
+
 | Phase | Name | Status |
 |-------|------|--------|
-| 1 | ESKF Core | ✓ Complete |
-| 2 | Visual Odometry Pipeline | Pending |
-| 3 | Satellite Matching + GPR | Pending |
-| 4 | MAVLink I/O | Pending |
-| 5 | End-to-End Pipeline Wiring | Pending |
-| 6 | Docker SITL Harness + CI | Pending |
-| 7 | Accuracy Validation | Pending |
+| 1 | Hexagonal Refactor & Composition Root | **Complete** (8/8 plans, 216 tests green) |
+| 2 | Acceptance Criteria + Test Taxonomy + Observability Spine | Pending |
+| 3 | Safety Anchor State Machine & Geometry-Gated Verifier | Pending |
+| 4 | Conditional Multi-Scale VPR + Flight Data Recorder | Pending |
+| 5 | MAVLink Source-Aware Output & Spoofing/Blackout Handling | Pending |
+| 6 | Real-Flight Fixture (Azaion 10.05.2026) + CLI + Per-Env Docker | Pending |
 
 ## Key Files
 
-- `.planning/PROJECT.md` — project context and requirements
-- `.planning/REQUIREMENTS.md` — 36 v1 requirements with traceability
-- `.planning/ROADMAP.md` — 7-phase execution plan
+- `.planning/PROJECT.md` — Stage 2 project context
+- `.planning/REQUIREMENTS.md` — 52 Stage 2 requirements with traceability
+- `.planning/ROADMAP.md` — Stage 2 roadmap, 6 phases
+- `.planning/archive/v1.0/` — Stage 1 historical record (PROJECT/REQUIREMENTS/ROADMAP/phases)
 - `.planning/codebase/` — codebase map (ARCHITECTURE, CONCERNS, STACK, etc.)
 - `_docs/01_solution/solution.md` — authoritative architecture spec
-- `_docs/00_problem/acceptance_criteria.md` — 43 test scenarios
+- `_docs/00_problem/acceptance_criteria.md` — to be rewritten with formal AC-1.x (Phase 2)
 
 ## Session Notes
 
-- Initialized 2026-04-01
-- Brownfield: scaffold exists (~2800 lines), critical algorithms missing (ESKF, MAVLink, real TRT/cuVSLAM)
-- cuVSLAM + TRT available only on Jetson; dev/CI uses OpenCV ORB stub + MockInferenceEngine
-- Pipeline direction: top-down (API → ESKF → VO → satellite → GPS_INPUT)
+- 2026-04-01 — Project initialized; Stage 1 brownfield scaffold (~2800 lines)
+- Stage 1 complete — 195 passing + 8 SITL skipped tests, all 7 phases shipped, archived to `.planning/archive/v1.0/`
+- 2026-05-10 — Stage 2 opened as independent iteration with own phase numbering (1–6); 52 requirements drafted
+- 2026-05-10 — Stage 2 ROADMAP.md created; 100% requirement coverage; traceability populated in REQUIREMENTS.md
+- Stage 2 strategy: refactor stage1 working code to hexagonal layout, re-implement try02 concepts (NOT layout details), formalize AC, add Azaion real-flight fixture
+- Code from stage1 is MVP — refactoring is allowed and expected; no regression in 195 stage1 tests is the floor
+- 2026-05-11 — Phase 1 complete: Plans 01-01 through 01-08 executed; 216/216 tests passing; ARCH-01..07 all satisfied
 
-## Phase 1 Execution Summary (2026-04-01)
+## Stage 2 Phase Dependency Order
 
-**Status:** ✓ Complete — All 3 plans executed, 35 tests passing
+```
+Phase 1 (ARCH refactor — Protocol surfaces stabilize first)
+   ↓
+Phase 2 (AC + TEST taxonomy + structlog spine)
+   ↓
+Phase 3 (SAFE state machine + VERIFY anchor gates)
+   ↓
+Phase 4 (Conditional VPR + FDR — needs trigger semantics from SAFE)
+   ↓
+Phase 5 (MAVOUT — source labels + spoofing + blackout — needs SAFE labels + FDR audit)
+   ↓
+Phase 6 (FIXTURE — Azaion real-flight + CLI + per-env Docker — exercises everything end-to-end)
+```
 
-**Deliverables:**
-- `src/gps_denied/schemas/eskf.py` (68 lines) — ESKF data contracts (ConfidenceTier, ESKFState, ESKFConfig, IMUMeasurement)
-- `src/gps_denied/core/eskf.py` (359 lines) — 15-state ESKF with IMU prediction, VO/satellite updates, confidence tiers
-- `src/gps_denied/core/coordinates.py` (176 lines added) — Real K-matrix projection, ray-ground intersection, gps_to_pixel inverse
-- `tests/test_eskf.py` (290 lines) — 18 ESKF unit tests
-- `tests/test_coordinates.py` (+200 lines) — 17 coordinate chain tests
+## Current Position
 
-**Requirements Covered:** ESKF-01 through ESKF-06 (all 6 Phase 1 requirements)
+Phase: 1 — Hexagonal Refactor & Composition Root
+Plan: 08 (COMPLETE — final plan of phase)
+Status: Phase 1 complete — all 8 plans executed, 216/216 tests green, ARCH-01..07 satisfied
+Last activity: 2026-05-11 — Plan 01-08 complete; build_pipeline factory + RuntimeConfig + YAML config shipped
 
-**Commits:** 4 total (schemas, core ESKF, coordinates, tests, summaries)
+## Key Decisions (Phase 1)
 
-**Verification:** pytest 35/35 passing (100% success)
+- ARCH-01: components/{vio,satellite_matcher,gpr,mavlink_io,anchor_verifier,safety_state,flight_recorder,coordinate_transforms}/ created with protocol.py + impls
+- ARCH-02: hot_types migration deferred to Phase 2 (Pydantic retained for 216-test stability)
+- ARCH-03: pipeline/composition.py build_pipeline(env) as explicit DI root
+- ARCH-04: core/ math files retained as single files (eskf, factor_graph, coordinates, chunk_manager, recovery, rotation)
+- ARCH-05: typing.Protocol throughout; orchestrator.py has zero concrete adapter imports
+- ARCH-06: config/{jetson,x86_dev,ci,sitl}.yaml + RuntimeConfig.env + YamlConfigSettingsSource
+- ARCH-07: 216 passed / 8 skipped / 0 failed (baseline was 216+8 skipped)

.planning/phases/01-hexagonal-refactor/01-06-SUMMARY.md

@@ -0,0 +1,101 @@
+---
+phase: "01"
+plan: "06"
+subsystem: mavlink_io
+tags: [refactor, hexagonal, mavlink, shim]
+dependency_graph:
+  requires: [01-05]
+  provides: [components/mavlink_io]
+  affects: [core/mavlink.py]
+tech_stack:
+  added: []
+  patterns: [shim-re-export, circular-import-avoidance-via-local-imports]
+key_files:
+  created:
+    - src/gps_denied/components/mavlink_io/pymavlink_bridge.py
+    - src/gps_denied/components/mavlink_io/mock_mavlink.py
+  modified:
+    - src/gps_denied/components/mavlink_io/__init__.py
+    - src/gps_denied/core/mavlink.py
+decisions:
+  - "Used local (deferred) imports of MockMAVConnection inside MAVLinkBridge methods to avoid circular import between pymavlink_bridge and mock_mavlink"
+  - "Shim re-exports all seven names including three private helpers (_confidence_to_fix_type, _eskf_to_gps_input, _unix_to_gps_time) per CRITICAL warning"
+metrics:
+  duration: "~5 minutes"
+  completed: "2026-05-11"
+  tasks: 5
+  files: 4
+---
+
+# Phase 01 Plan 06: MAVLink I/O Split Summary
+
+Split `core/mavlink.py` (483 LOC) into component modules under `components/mavlink_io/`, replacing the original with a shim that re-exports all public and private names verbatim.
+
+## LOC Distribution
+
+| File | LOC | Contents |
+|------|-----|----------|
+| `components/mavlink_io/pymavlink_bridge.py` | 455 | MAVLinkBridge class + 3 module-level helpers + pymavlink conditional import |
+| `components/mavlink_io/mock_mavlink.py` | 30 | MockMAVConnection (no-op for dev/CI) |
+| `core/mavlink.py` (shim) | 29 | Re-export shim only |
+| `components/mavlink_io/__init__.py` | 20 | Package surface |
+
+Original: 483 LOC → split across 4 files (514 total including shim and `__init__.py`).
+
+## Test Counts
+
+| Test file | Result |
+|-----------|--------|
+| `tests/test_mavlink.py` | 32 passed |
+| `tests/test_gps_input_encoding.py` | included in the 32 above |
+| Full regression (`tests/`) | 216 passed, 8 skipped |
+
+Regression floor: 216 passed (baseline). Status: MAINTAINED.
+
+## Private Helper Verification
+
+The three underscore names required by `test_mavlink.py` and `test_gps_input_encoding.py` resolve correctly via the shim:
+
+```
+python -c "from gps_denied.core.mavlink import _confidence_to_fix_type, _eskf_to_gps_input, _unix_to_gps_time; print('private helpers ok')"
+# Output: private helpers ok
+```
+
+All three are exported from `core/mavlink.py` → `components/mavlink_io/pymavlink_bridge.py` → callable.
+
+## `_PYMAVLINK_AVAILABLE` on Dev Machine
+
+```
+_PYMAVLINK_AVAILABLE = True
+```
+
+pymavlink is installed on this development machine, so `MAVLinkBridge._open_connection()` will attempt a real connection before falling back to `MockMAVConnection`.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Circular import between pymavlink_bridge and mock_mavlink**
+
+- **Found during:** Task 1 (design review before writing)
+- **Issue:** `pymavlink_bridge.py` (MAVLinkBridge) uses `isinstance(self._conn, MockMAVConnection)` checks. If `mock_mavlink.py` were imported at module level in `pymavlink_bridge.py`, and `__init__.py` imports both, a circular import chain would form.
+- **Fix:** Used local (deferred) imports of `MockMAVConnection` inside each method that references it (`_send_gps_input`, `_recv_imu`, `_send_reloc_request`, `_send_telemetry`, `_open_connection`). This matches the pattern used in similar hexagonal refactors in this codebase.
+- **Files modified:** `pymavlink_bridge.py`
+- **Commit:** f965ac7
+
+## Known Stubs
+
+None. All data paths are wired: bridge reads from live ESKFState, writes to real or mock MAVLink connection.
+
+## Threat Flags
+
+None. No new network endpoints or auth paths introduced. The MAVLink UART connection was already present in the original `core/mavlink.py`.
+
+## Self-Check: PASSED
+
+- `src/gps_denied/components/mavlink_io/pymavlink_bridge.py` — FOUND
+- `src/gps_denied/components/mavlink_io/mock_mavlink.py` — FOUND
+- `src/gps_denied/components/mavlink_io/__init__.py` — FOUND (updated)
+- `src/gps_denied/core/mavlink.py` — FOUND (shim, 29 LOC)
+- Commit f965ac7 — FOUND
+- 216 tests passed — CONFIRMED

.planning/phases/01-hexagonal-refactor/01-07-SUMMARY.md

@@ -0,0 +1,152 @@
+---
+phase: "01-hexagonal-refactor"
+plan: "01-07"
+subsystem: "core-restructure"
+tags: ["refactor", "protocol", "pipeline", "abc-to-protocol", "shim"]
+
+dependency_graph:
+  requires: ["01-05", "01-06"]
+  provides: ["pipeline-package", "factor-graph-module", "testing-benchmark-module"]
+  affects: ["core/graph.py", "core/processor.py", "core/pipeline.py", "core/results.py", "core/sse.py", "core/benchmark.py", "core/chunk_manager.py", "core/recovery.py", "core/models.py", "core/rotation.py"]
+
+tech_stack:
+  added: []
+  patterns: ["typing.Protocol with @runtime_checkable", "shim re-export pattern", "package decomposition"]
+
+key_files:
+  created:
+    - src/gps_denied/core/factor_graph.py
+    - src/gps_denied/pipeline/__init__.py
+    - src/gps_denied/pipeline/orchestrator.py
+    - src/gps_denied/pipeline/image_input.py
+    - src/gps_denied/pipeline/result_manager.py
+    - src/gps_denied/pipeline/sse_streamer.py
+    - src/gps_denied/testing/benchmark.py
+  modified:
+    - src/gps_denied/core/graph.py (shim)
+    - src/gps_denied/core/processor.py (shim)
+    - src/gps_denied/core/pipeline.py (shim)
+    - src/gps_denied/core/results.py (shim)
+    - src/gps_denied/core/sse.py (shim)
+    - src/gps_denied/core/benchmark.py (shim)
+    - src/gps_denied/core/chunk_manager.py (ABC→Protocol in-place)
+    - src/gps_denied/core/recovery.py (ABC→Protocol in-place)
+    - src/gps_denied/core/models.py (ABC→Protocol in-place)
+    - src/gps_denied/core/rotation.py (ABC→Protocol in-place)
+    - pyproject.toml (ruff per-file-ignores updated)
+
+decisions:
+  - "Protocol subclassing is valid Python — FactorGraphOptimizer(IFactorGraphOptimizer) kept as-is"
+  - "pipeline/result_manager.py imports from pipeline/sse_streamer.py directly, avoiding shim chain"
+  - "core/results.py and core/sse.py shims kept lean; no circular import issues"
+  - "pipeline/orchestrator.py internal imports updated to new paths; test shims handle old paths"
+  - "src/gps_denied/testing/harness.py and api/deps.py left using shim paths (backward-compat)"
+
+metrics:
+  duration: "~8 minutes"
+  completed: "2026-05-11"
+  tasks_completed: 6
+  files_created: 7
+  files_modified: 11
+---
+
+# Phase 01-hexagonal-refactor Plan 07: Factor Graph, Pipeline Package, Benchmark, Protocol Conversions Summary
+
+**One-liner:** Extracted pipeline orchestration into `pipeline/` package, moved factor graph to `core/factor_graph.py`, benchmarks to `testing/benchmark.py`, and converted 5 ABCs to `typing.Protocol` with `@runtime_checkable`.
+
+## File Moves Performed
+
+| Source | Target | Method |
+|--------|--------|--------|
+| `core/graph.py` (IFactorGraphOptimizer) | `core/factor_graph.py` | Copy + ABC→Protocol, shim left at source |
+| `core/processor.py` (FlightProcessor) | `pipeline/orchestrator.py` | Copy + internal imports updated, shim left at source |
+| `core/pipeline.py` (ImageInputPipeline) | `pipeline/image_input.py` | Copy verbatim, shim left at source |
+| `core/results.py` (ResultManager) | `pipeline/result_manager.py` | Copy + SSE import updated, shim left at source |
+| `core/sse.py` (SSEEventStreamer) | `pipeline/sse_streamer.py` | Copy verbatim, shim left at source |
+| `core/benchmark.py` (AccuracyBenchmark et al.) | `testing/benchmark.py` | Copy verbatim, shim left at source |
+
+## ABCs Converted to Protocol (5 total)
+
+| Interface | File | Method count |
+|-----------|------|-------------|
+| `IFactorGraphOptimizer` | `core/factor_graph.py` | 13 methods |
+| `IRouteChunkManager` | `core/chunk_manager.py` | 6 methods |
+| `IFailureRecoveryCoordinator` | `core/recovery.py` | 2 methods |
+| `IModelManager` | `core/models.py` | 5 methods |
+| `IImageMatcher` | `core/rotation.py` | 1 method |
+
+**Pattern applied to each:**
+- Removed `from abc import ABC, abstractmethod`
+- Added `from typing import Protocol, runtime_checkable`
+- Replaced `class IXxx(ABC):` with `@runtime_checkable\nclass IXxx(Protocol):`
+- Dropped `@abstractmethod` decorators; replaced `pass` bodies with `...`
+- Concrete classes continue to subclass the Protocol (valid Python)
+
+## pyproject.toml Changes
+
+```diff
+ [tool.ruff.lint.per-file-ignores]
+-"src/gps_denied/core/graph.py" = ["E501"]
++"src/gps_denied/core/factor_graph.py" = ["E501"]
+-"src/gps_denied/core/metric.py" = ["E501"]
++"src/gps_denied/components/satellite_matcher/metric_refinement.py" = ["E501"]
+ "src/gps_denied/core/chunk_manager.py" = ["E501"]
+```
+
+## Test Counts
+
+| | Count |
+|--|--|
+| Baseline (before plan) | 216 passed, 8 skipped |
+| After plan | 216 passed, 8 skipped |
+| Regression floor met | YES |
+
+## Internal Import Updates in Non-Test Source Files
+
+`pipeline/orchestrator.py` (canonical location of `FlightProcessor`):
+- `from gps_denied.core.pipeline import ImageInputPipeline` → `from gps_denied.pipeline.image_input import ImageInputPipeline`
+- `from gps_denied.core.results import ResultManager` → `from gps_denied.pipeline.result_manager import ResultManager`
+- `from gps_denied.core.sse import SSEEventStreamer` → `from gps_denied.pipeline.sse_streamer import SSEEventStreamer`
+
+`pipeline/result_manager.py` (canonical location of `ResultManager`):
+- `from gps_denied.core.sse import SSEEventStreamer` → `from gps_denied.pipeline.sse_streamer import SSEEventStreamer`
+
+`src/gps_denied/testing/harness.py` and `src/gps_denied/api/deps.py`: left using legacy `core.*` shim paths — they continue to work transparently.
+
+## Protocol Conversion Edge Cases
+
+1. **`IFactorGraphOptimizer` in `core/factor_graph.py`**: The concrete class `FactorGraphOptimizer` subclasses the Protocol. Python allows this and it provides structural typing via `@runtime_checkable`. The existing `isinstance(x, IFactorGraphOptimizer)` calls in tests will work.
+
+2. **Long method signatures in `factor_graph.py`**: The `E501` ruff ignore was updated from `core/graph.py` to `core/factor_graph.py` — signatures like `add_relative_factor_to_chunk(...)` with 6 parameters exceed 120 chars.
+
+3. **`chunk_manager.py` import of `IFactorGraphOptimizer`**: Still imports from `gps_denied.core.graph` (which shims to `factor_graph`) — no change needed, backward-compat maintained.
+
+4. **`IImageMatcher` in `rotation.py`**: Used as a DI parameter type in `try_rotation_sweep`. Concrete implementations (e.g., `MetricRefinement` from `components/satellite_matcher`) are not subclasses but satisfy the Protocol structurally.
+
+5. **`IModelManager` return type `InferenceEngine`**: `InferenceEngine` is a Pydantic model, not changed. Protocol stub uses `...` which satisfies mypy for structural checks.
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None introduced by this plan. All moved code is functionally complete.
+
+## Threat Flags
+
+None. No new network endpoints, auth paths, or file access patterns introduced by these refactors.
+
+## Self-Check: PASSED
+
+Files created:
+- FOUND: src/gps_denied/core/factor_graph.py
+- FOUND: src/gps_denied/pipeline/__init__.py
+- FOUND: src/gps_denied/pipeline/orchestrator.py
+- FOUND: src/gps_denied/pipeline/image_input.py
+- FOUND: src/gps_denied/pipeline/result_manager.py
+- FOUND: src/gps_denied/pipeline/sse_streamer.py
+- FOUND: src/gps_denied/testing/benchmark.py
+
+Commit: 5a60c1e — FOUND
+Regression: 216 passed >= 216 baseline — PASSED

_docs/01_solution/decisions/0002-hexagonal-architecture-stage2.md

@@ -0,0 +1,51 @@
+# ADR 0002 — Hexagonal / Ports-and-Adapters Architecture for Stage 2
+
+**Date:** 2026-05-11
+**Status:** Accepted
+**Supersedes:** —
+**Implemented in:** Phase 1 (2026-05-11)
+
+---
+
+## Context
+
+Stage 1 used a flat `src/gps_denied/core/` layout where all implementations lived as peers — `vo.py`, `gpr.py`, `mavlink.py`, `satellite.py`, `metric.py`, `graph.py`, `processor.py`, etc. ABCs were scattered across files. The pipeline was wired inline inside `app.py:lifespan`.
+
+For Stage 2 we evaluated three architectural options:
+
+**Option A — Continue flat monolith**: keep `core/` as-is, add new code alongside existing files. Lowest friction, but backends are not swappable without editing the orchestrator; no clear seam for Jetson vs dev implementations.
+
+**Option B — Hexagonal / ports-and-adapters**: one folder per swappable component under `components/`, each with a `protocol.py` (the port) and concrete adapter files (the adapters). Math stays concentrated in `core/`. Explicit DI composition root `pipeline/composition.py` wires env-specific adapters. Test the orchestrator against Protocols — concrete adapters only appear in composition.py.
+
+**Option C — Microservices with IPC**: separate processes per component. Rejected immediately — adds network latency on a <400ms budget, no hardware justification.
+
+The parallel `try02` branch chose a similar hexagonal layout but used Pydantic models on the per-frame hot path. We observed in benchmarks that per-frame Pydantic validation has measurable overhead at 0.7fps on Jetson's 8GB shared pool. We chose Option B but diverged from try02 on the hot-path type decision (see ADR 0003).
+
+## Decision
+
+Adopt **Option B — hexagonal / ports-and-adapters** with the following rules:
+
+1. Every swappable backend gets its own folder: `src/gps_denied/components/{vio, satellite_matcher, gpr, mavlink_io, anchor_verifier, safety_state, flight_recorder, coordinate_transforms}/`
+2. Each component folder contains `protocol.py` (a `typing.Protocol` port) + one or more concrete adapter files.
+3. `core/` is retained for concentrated math (ESKF, factor graph, RANSAC, coordinates) — these are pure-function single files, NOT split into `interfaces.py + impl.py`.
+4. The orchestrator (`pipeline/orchestrator.py`) imports only Protocols — no concrete adapters. Only `pipeline/composition.py` imports concrete adapters.
+5. Per-environment wiring via `build_pipeline(env: Literal["jetson","x86_dev","ci","sitl"]) -> FlightProcessor`.
+
+## Consequences
+
+**Positive:**
+- cuVSLAM backend (Jetson) vs ORB-SLAM3 stub (dev/CI) are swapped by changing a single `create_vo_backend()` call in `composition.py` — no orchestrator edits.
+- New component (e.g., Safety Anchor State Machine in Phase 3) gets its own folder with a Protocol first; the orchestrator only sees the Protocol.
+- Tests inject mock adapters directly via `attach_components()` — no monkey-patching needed.
+- `orchestrator.py` passes ARCH-05 check: zero concrete adapter imports verified via grep.
+
+**Negative / Trade-offs:**
+- Every moved file leaves a re-export shim at the old path to keep 216 existing tests green. Shims accumulate tech debt until Phase 2 removes them.
+- `Pose` (Pydantic) inside `factor_graph.py` has mutable `.position` assignments at lines 182–297. Converting it to a frozen dataclass requires rewriting those mutation sites — deferred to Phase 2 to avoid breaking the regression floor.
+- 8 component folders with stub Protocols for Phase 3/4 components (anchor_verifier, safety_state, flight_recorder, coordinate_transforms) add file count without code yet — this is intentional scaffolding.
+
+## Implementation Notes
+
+- Phase 1 (Plans 01-08) implemented this decision end-to-end. 216/216 tests pass.
+- Private helpers `_confidence_to_fix_type`, `_eskf_to_gps_input`, `_unix_to_gps_time` are tested directly by `tests/test_mavlink.py`. The `core/mavlink.py` shim re-exports them verbatim. When shims are removed in Phase 2, those tests must be updated to import from `components/mavlink_io/pymavlink_bridge`.
+- Faiss numpy fallback stays inline in `components/gpr/faiss_gpr.py:load_index()` — splitting into a sibling `numpy_gpr.py` is Phase 4 (VPR-03) work.

_docs/01_solution/decisions/0003-hot-path-dataclasses-vs-pydantic.md

@@ -0,0 +1,52 @@
+# ADR 0003 — `@dataclass(slots=True, frozen=True)` on Hot Path; Pydantic at Boundaries Only
+
+**Date:** 2026-05-11
+**Status:** Accepted (partially implemented — Phase 1 scaffolded; full migration Phase 2)
+**Supersedes:** —
+**Implemented in:** Phase 1 scaffold; Phase 2 full migration
+
+---
+
+## Context
+
+Stage 1 and the parallel `try02` branch both used Pydantic models (`BaseModel`) for per-frame data types: `FrameState`, `IMUSample`, `PositionEstimate`, `VOEstimate`, `SatelliteAnchor`. Pydantic v2 is fast, but on the per-frame path at 0.7fps with Jetson's shared 8GB CPU/GPU pool, every `model_validate()` or `__init__` triggers field validation, type coercion, and `__dict__` allocation — none of which we need for internal pipeline types whose values come from trusted numpy operations.
+
+try02's design doc noted this overhead but kept Pydantic for "consistency." We rejected this trade-off.
+
+Pydantic remains genuinely valuable at system boundaries: REST API request/response parsing (FastAPI), config loading (pydantic-settings), and DB schema validation (SQLAlchemy models). At those boundaries, external input is untrusted and validation catches bugs early. On the per-frame path, input comes from our own numpy operations — validation is redundant overhead.
+
+## Decision
+
+**Hot-path data types** use `@dataclass(slots=True, frozen=True)` from Python 3.10+:
+- `FrameState` — per-frame snapshot passed through the pipeline
+- `IMUSample` — raw IMU measurement from MAVLink
+- `PositionEstimate` — output of ESKF, input to GPS_INPUT encoding
+- `VOEstimate` — output of visual odometry backend
+- `SatelliteAnchor` — accepted satellite match result
+
+These live in `src/gps_denied/hot_types/`. Old schema paths (`gps_denied.schemas.eskf`, `gps_denied.schemas.vo`, etc.) are shimmed to re-export from `hot_types` for test compatibility.
+
+**Boundary types** keep Pydantic:
+- FastAPI request/response schemas (`src/gps_denied/schemas/`)
+- `AppSettings` / `RuntimeConfig` (pydantic-settings)
+- `AsyncSQLAlchemy` models
+- `Pose` — special case (see below)
+
+## Consequences
+
+**Positive:**
+- `slots=True` eliminates `__dict__` per instance — reduces per-frame allocations on a memory-constrained target.
+- `frozen=True` prevents accidental mutation deep in the pipeline — catches bugs at assignment time rather than as silent state corruption.
+- `dataclasses.replace()` for modified copies is explicit and cheap.
+- No validation overhead on trusted internal data.
+
+**Negative / Exceptions:**
+- **`Pose` stays Pydantic** in Phase 1. `core/factor_graph.py` mutates `pose.position` at lines 182, 207, 230, 297 using `pose.position[0] = x` style assignment. Converting `Pose` to a frozen dataclass requires rewriting 4 mutation sites to use `dataclasses.replace()`. Deferred to Phase 2 to avoid breaking the regression floor during the Phase 1 rename wave.
+- **`GPSPoint` stays Pydantic** — it appears in REST responses and is already at a boundary. No change needed.
+- `dataclasses.replace()` is more verbose than Pydantic's `.model_copy(update={...})`. Acceptable trade-off.
+
+## Implementation Notes
+
+- `src/gps_denied/hot_types/` scaffolded in Plan 01-01 with 5 types + `__init__.py`.
+- Old schema files (`schemas/eskf.py`, `schemas/vo.py`, `schemas/satellite.py`, `schemas/metric.py`, `schemas/rotation.py`) converted to re-export shims pointing to `hot_types`.
+- Phase 2 work: migrate all `Pose` mutation sites to `dataclasses.replace()`; remove schema shims; update tests to import from `hot_types` directly.

_docs/01_solution/decisions/0004-stage2-as-independent-iteration.md

@@ -0,0 +1,52 @@
+# ADR 0004 — Stage 2 as Independent Iteration (Own Phases 1–6)
+
+**Date:** 2026-05-10
+**Status:** Accepted
+**Supersedes:** —
+
+---
+
+## Context
+
+After Stage 1 delivered a working MVP (195 tests, ESKF + cuVSLAM + satellite matching + MAVLink pipeline), the question was how to structure the next development cycle. Two options:
+
+**Option A — Continue Stage 1 phase numbering**: treat Stage 2 as Phases 8–13 (continuing from Stage 1's Phase 7). The roadmap grows linearly. Decisions from Stage 1 are "inherited constraints."
+
+**Option B — Fresh iteration**: Stage 2 is a self-contained iteration with its own Phases 1–6, its own requirements document, its own success criteria. Stage 1 code is treated as MVP starting capital — refactoring is expected and allowed. Only AC-driven test outcomes are sacred.
+
+The problem with Option A: treating Stage 1 phases as immutable history means we cannot refactor the architecture without numbering collisions, and it creates psychological friction against rewriting decisions that turned out to be suboptimal. The GSD workflow (milestone → phases → plans) works cleanest when each milestone has its own numbered phase space.
+
+The parallel `try02` branch from a different team demonstrated a completely different architectural take on the same problem in the same time window. We wanted to be able to incorporate their concept-level ideas freely, not be constrained by compatibility with Stage 1's exact module boundaries.
+
+## Decision
+
+Each development stage is an independent iteration:
+- Own `REQUIREMENTS.md` (52 v2 requirements vs 36 v1 requirements)
+- Own `ROADMAP.md` (Phases 1–6)
+- Own phase numbering starting from 1
+- Stage 1 artifacts archived in `.planning/archive/v1.0/` as historical record, not active backlog
+- Stage 1 code treated as MVP — any file can be refactored, moved, or replaced if the tests still pass
+
+**Stage 2 sources of starting capital:**
+- Stage 1 codebase (own work): ESKF, VO, GPR, MAVLink, pipeline, 216 passing tests
+- try02 branch (parallel team): concept-level ideas harvested and re-implemented — Safety Anchor State Machine, Geometry-Gated Anchor Verifier, FDR, Conditional VPR, formal AC document, test taxonomy
+- Azaion 10.05.2026 real-flight dataset: tlog + 6min video used as integration fixture
+
+## Consequences
+
+**Positive:**
+- Clean phase numbering — Phase 1 of Stage 2 is the hexagonal refactor, unambiguous
+- Freedom to refactor Stage 1 code without "breaking" numbered phases
+- try02 ideas integrated by re-implementation (not git merge) — avoids namespace collisions and allows selective adoption
+- `stage2` branch starts at HEAD = stage1, with Stage 2 work built on top
+
+**Negative / Trade-offs:**
+- Stage 1 tests that tested specific module paths (e.g., `from gps_denied.core.vo import`) become shim-dependent after Phase 1 moves code. Shim cleanup is Phase 2 work — tests are not edited during Phase 1 to preserve the regression floor.
+- The `try02` branch is checked out as a worktree at `../gps-denied-onboard-try02/` for reading. We do NOT merge from it — ideas are read and re-implemented from scratch.
+
+## Stage Boundary Convention
+
+At stage completion:
+1. Snapshot `PROJECT.md` / `REQUIREMENTS.md` / `ROADMAP.md` / `phases/` → `.planning/archive/v[X.Y]/`
+2. Open Stage N+1 with a fresh roadmap starting at Phase 1
+3. Carry forward only validated decisions and unresolved parking-lot items

config/ci.yaml

@@ -0,0 +1 @@
+env: ci

config/jetson.yaml

@@ -0,0 +1 @@
+env: jetson

config/sitl.yaml

@@ -0,0 +1 @@
+env: sitl

config/x86_dev.yaml

@@ -0,0 +1 @@
+env: x86_dev

pyproject.toml

@@ -19,6 +19,7 @@ dependencies = [
     "opencv-python-headless>=4.9,<4.11",  # 4.11+ requires numpy>=2.0 (incompatible with GTSAM)
     "gtsam>=4.3a0",
     "pymavlink>=2.4",
+    "pyyaml>=6.0",
 ]
 
 [project.optional-dependencies]
@@ -42,8 +43,8 @@ line-length = 120
 
 [tool.ruff.lint.per-file-ignores]
 # Abstract interfaces have long method signatures — allow up to 170
-"src/gps_denied/core/graph.py" = ["E501"]
-"src/gps_denied/core/metric.py" = ["E501"]
+"src/gps_denied/core/factor_graph.py" = ["E501"]
+"src/gps_denied/components/satellite_matcher/metric_refinement.py" = ["E501"]
 "src/gps_denied/core/chunk_manager.py" = ["E501"]
 
 [tool.ruff.lint]

src/gps_denied/api/deps.py

@@ -5,7 +5,7 @@ from fastapi import Depends, HTTPException, Request
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from gps_denied.config import get_settings
+from gps_denied.config import RuntimeConfig, get_settings
 from gps_denied.core.processor import FlightProcessor
 from gps_denied.core.sse import SSEEventStreamer
 from gps_denied.db.engine import get_session
@@ -65,14 +65,23 @@ async def get_flight_processor(
 ) -> FlightProcessor:
     global _processor
     if _processor is None:
-        eskf_config = getattr(request.app.state, "eskf_config", None)
-        _processor = FlightProcessor(repo, sse, eskf_config=eskf_config)
-        # Підключаємо pipeline компоненти з lifespan
-        components = getattr(request.app.state, "pipeline_components", None)
-        if components:
-            _processor.attach_components(**components)
-    # Оновлюємо repo (нова сесія на кожен запит)
+        # Prefer the processor already built by lifespan (via build_pipeline)
+        lifespan_processor = getattr(request.app.state, "processor", None)
+        if lifespan_processor is not None:
+            _processor = lifespan_processor
+        else:
+            # Fallback: build pipeline directly (e.g. in tests without lifespan)
+            from gps_denied.pipeline import build_pipeline
+            _settings = RuntimeConfig()
+            _processor = build_pipeline(
+                env=_settings.env,
+                config=_settings,
+                repository=repo,
+                streamer=sse,
+            )
+    # Оновлюємо repo та streamer (нова сесія на кожен запит)
     _processor.repository = repo
+    _processor.streamer = sse
     return _processor
 
 

src/gps_denied/app.py

@@ -7,70 +7,50 @@ from fastapi import FastAPI
 
 from gps_denied import __version__
 from gps_denied.api.routers import flights
-from gps_denied.config import get_settings
+from gps_denied.config import RuntimeConfig
+from gps_denied.pipeline import build_pipeline
 
 logger = logging.getLogger(__name__)
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    """Initialise core pipeline components on startup."""
-    from gps_denied.core.chunk_manager import RouteChunkManager
-    from gps_denied.core.coordinates import CoordinateTransformer
-    from gps_denied.core.gpr import GlobalPlaceRecognition
-    from gps_denied.core.graph import FactorGraphOptimizer
-    from gps_denied.core.mavlink import MAVLinkBridge
-    from gps_denied.core.metric import MetricRefinement
-    from gps_denied.core.models import ModelManager
-    from gps_denied.core.recovery import FailureRecoveryCoordinator
-    from gps_denied.core.rotation import ImageRotationManager
-    from gps_denied.core.satellite import SatelliteDataManager
-    from gps_denied.core.vo import create_vo_backend
-    from gps_denied.schemas.eskf import ESKFConfig
-    from gps_denied.schemas.graph import FactorGraphConfig
+    """Initialise core pipeline components on startup via build_pipeline."""
+    cfg = RuntimeConfig()
+    processor = build_pipeline(env=cfg.env, config=cfg)
 
-    settings = get_settings()
+    # Retrieve MAVLink bridge from processor internals for lifecycle management
+    mavlink = processor._mavlink
 
-    mm = ModelManager(engine_dir=str(settings.models.weights_dir))
-    vo = create_vo_backend(model_manager=mm)
-    gpr = GlobalPlaceRecognition(mm)
-    metric = MetricRefinement(mm)
-    graph = FactorGraphOptimizer(FactorGraphConfig())
-    chunk_mgr = RouteChunkManager(graph)
-    recovery = FailureRecoveryCoordinator(chunk_mgr, gpr, metric)
-    rotation = ImageRotationManager(mm)
-    coord = CoordinateTransformer()
-    satellite = SatelliteDataManager(tile_dir=settings.satellite.tile_dir)
-    mavlink = MAVLinkBridge(
-        connection_string=settings.mavlink.connection,
-        output_hz=settings.mavlink.output_hz,
-        telemetry_hz=settings.mavlink.telemetry_hz,
-    )
-
-    # ESKF config from env vars (per-airframe tuning)
-    eskf_config = ESKFConfig(**settings.eskf.model_dump())
-
-    # Store on app.state so deps can access them
+    app.state.processor = processor
+    app.state.config = cfg
+    # Keep backwards-compat key so any code reading pipeline_components still works
     app.state.pipeline_components = {
-        "vo": vo, "gpr": gpr, "metric": metric,
-        "graph": graph, "recovery": recovery,
-        "chunk_mgr": chunk_mgr, "rotation": rotation,
-        "coord": coord, "satellite": satellite,
+        "vo": processor._vo,
+        "gpr": processor._gpr,
+        "metric": processor._metric,
+        "graph": processor._graph,
+        "recovery": processor._recovery,
+        "chunk_mgr": processor._chunk_mgr,
+        "rotation": processor._rotation,
+        "coord": processor._coord,
+        "satellite": processor._satellite,
         "mavlink": mavlink,
     }
-    app.state.eskf_config = eskf_config
+    app.state.eskf_config = processor._eskf_config
 
     logger.info(
-        "Pipeline ready — MAVLink: %s, tiles: %s",
-        settings.mavlink.connection, settings.satellite.tile_dir,
+        "Pipeline ready — env=%s, MAVLink: %s, tiles: %s",
+        cfg.env, cfg.mavlink.connection, cfg.satellite.tile_dir,
     )
     yield
 
-    # Cleanup
-    try:
-        await mavlink.stop()
-    except Exception:
-        pass
+    # Cleanup MAVLink on shutdown
+    if mavlink is not None:
+        try:
+            await mavlink.stop()
+        except Exception:
+            pass
     app.state.pipeline_components = None
 
 

src/gps_denied/components/__init__.py

@@ -0,0 +1,6 @@
+"""Hexagonal component packages (Phase 1, ARCH-01).
+
+Each subpackage hosts the Protocol surface for a swappable component.
+Concrete adapters land here in Plans 03-07; Phase 1 only defines the
+Protocols (Plan 01-02) so later migrations only update import paths.
+"""

src/gps_denied/components/anchor_verifier/protocol.py

@@ -0,0 +1,37 @@
+"""Protocol surface for the anchor_verifier component (Phase 3, VERIFY-01..05).
+
+Phase 1: stub only — semantics filled in Phase 3. The Protocol must
+exist now so the ARCH-01 directory inventory is complete at end of
+Phase 1.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from gps_denied.hot_types.alignment_result import AlignmentResult
+from gps_denied.hot_types.satellite_anchor import SatelliteAnchor
+
+
+@dataclass(slots=True, frozen=True)
+class VerifierDecision:
+    """Result of an :meth:`AnchorVerifier.verify` call.
+
+    Phase 3 will refine the rejection-reason taxonomy (currently free-text:
+    ``too_few_inliers`` / ``mre_above_threshold`` / ``degenerate_homography``
+    / ``freshness_expired``).
+    """
+
+    accepted: bool
+    anchor: SatelliteAnchor | None = None
+    rejection_reason: str | None = None
+    inlier_count: int = 0
+    mean_reprojection_error_px: float = 0.0
+    homography_condition_number: float = 0.0
+
+
+@runtime_checkable
+class AnchorVerifier(Protocol):
+    """Geometry-gated anchor verifier. Filled in Phase 3."""
+
+    def verify(self, candidate: AlignmentResult) -> VerifierDecision: ...

src/gps_denied/components/coordinate_transforms/protocol.py

@@ -0,0 +1,68 @@
+"""Protocol surface for the coordinate_transforms component (ARCH-05).
+
+Per ARCH-04 the implementation stays in ``core/coordinates.py`` —
+this directory holds ONLY the Protocol so the ARCH-01 directory
+inventory is complete. Method signatures mirror the concrete
+``CoordinateTransformer`` public surface.
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+from gps_denied.schemas import CameraParameters, GPSPoint
+
+
+@runtime_checkable
+class CoordinateTransformsProtocol(Protocol):
+    """ENU origin management + WGS84⇄ENU⇄pixel transforms."""
+
+    def set_enu_origin(self, flight_id: str, origin_gps: GPSPoint) -> None: ...
+
+    def get_enu_origin(self, flight_id: str) -> GPSPoint: ...
+
+    def gps_to_enu(
+        self, flight_id: str, gps: GPSPoint
+    ) -> tuple[float, float, float]: ...
+
+    def enu_to_gps(
+        self, flight_id: str, enu: tuple[float, float, float]
+    ) -> GPSPoint: ...
+
+    def pixel_to_gps(
+        self,
+        flight_id: str,
+        pixel: tuple[float, float],
+        frame_pose: dict,
+        camera_params: CameraParameters,
+        altitude: float,
+        quaternion: np.ndarray | None = None,
+    ) -> GPSPoint: ...
+
+    def gps_to_pixel(
+        self,
+        flight_id: str,
+        gps: GPSPoint,
+        frame_pose: dict,
+        camera_params: CameraParameters,
+        altitude: float,
+        quaternion: np.ndarray | None = None,
+    ) -> tuple[float, float]: ...
+
+    def image_object_to_gps(
+        self,
+        flight_id: str,
+        frame_id: int,
+        object_pixel: tuple[float, float],
+        frame_pose: dict | None = None,
+        camera_params: CameraParameters | None = None,
+        altitude: float = 100.0,
+        quaternion: np.ndarray | None = None,
+    ) -> GPSPoint: ...
+
+    def transform_points(
+        self,
+        points: list[tuple[float, float]],
+        transformation: list[list[float]],
+    ) -> list[tuple[float, float]]: ...

src/gps_denied/components/flight_recorder/protocol.py

@@ -0,0 +1,40 @@
+"""Protocol surface for the flight_recorder component (Phase 4, FDR-01..06).
+
+Phase 1: stub only — Phase 4 lands the in-memory + disk implementations
+behind this Protocol.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Protocol, runtime_checkable
+
+
+class RecorderHealth(str, Enum):
+    """Health tier of the flight-data recorder (FDR-04)."""
+
+    OK = "ok"
+    DEGRADED = "degraded"  # >= 90% storage
+    CRITICAL = "critical"  # storage limit reached
+
+
+@dataclass(slots=True, frozen=True)
+class FdrExportResult:
+    """Outcome of :meth:`FlightRecorder.export`."""
+
+    flight_id: str
+    segment_count: int
+    total_bytes: int
+    path: str | None = None  # set for DiskFlightRecorder, None for in-memory
+
+
+@runtime_checkable
+class FlightRecorder(Protocol):
+    """Append-only flight-data recorder per FDR-01. Filled in Phase 4."""
+
+    def append_event(self, event: dict[str, Any]) -> None: ...
+
+    def export(self) -> FdrExportResult: ...
+
+    @property
+    def health(self) -> RecorderHealth: ...

src/gps_denied/components/gpr/__init__.py

@@ -0,0 +1,22 @@
+"""GPR component barrel exports.
+
+``GlobalPlaceRecognition`` resolves to the Faiss-backed implementation
+(faiss_gpr.py).  The structural Protocol lives in protocol.py and is
+re-exported as ``IGlobalPlaceRecognition``.
+"""
+
+from gps_denied.components.gpr.faiss_gpr import (  # noqa: F401
+    GlobalPlaceRecognition,
+    _faiss,
+    _FAISS_AVAILABLE,
+)
+from gps_denied.components.gpr.protocol import (  # noqa: F401
+    IGlobalPlaceRecognition,
+)
+
+__all__ = [
+    "GlobalPlaceRecognition",
+    "IGlobalPlaceRecognition",
+    "_faiss",
+    "_FAISS_AVAILABLE",
+]

src/gps_denied/components/gpr/faiss_gpr.py

@@ -0,0 +1,269 @@
+"""Faiss-backed GlobalPlaceRecognition with inline numpy fallback.
+
+Phase 4 (VPR-03) may split numpy fallback into a sibling module.
+"""
+
+import json
+import logging
+import os
+from abc import ABC, abstractmethod
+from typing import Dict, List
+
+import numpy as np
+
+from gps_denied.core.models import IModelManager
+from gps_denied.schemas import GPSPoint
+from gps_denied.schemas.gpr import DatabaseMatch, TileCandidate
+from gps_denied.schemas.satellite import TileBounds
+
+logger = logging.getLogger(__name__)
+
+# Attempt to import Faiss (optional — only available on Jetson or with faiss-cpu installed)
+try:
+    import faiss as _faiss  # type: ignore
+    _FAISS_AVAILABLE = True
+    logger.info("Faiss available — real index search enabled")
+except ImportError:
+    _faiss = None  # type: ignore
+    _FAISS_AVAILABLE = False
+    logger.info("Faiss not available — using numpy L2 fallback for GPR")
+
+
+class IGlobalPlaceRecognition(ABC):
+    @abstractmethod
+    def retrieve_candidate_tiles(self, image: np.ndarray, top_k: int) -> List[TileCandidate]:
+        pass
+
+    @abstractmethod
+    def compute_location_descriptor(self, image: np.ndarray) -> np.ndarray:
+        pass
+
+    @abstractmethod
+    def query_database(self, descriptor: np.ndarray, top_k: int) -> List[DatabaseMatch]:
+        pass
+
+    @abstractmethod
+    def rank_candidates(self, candidates: List[TileCandidate]) -> List[TileCandidate]:
+        pass
+
+    @abstractmethod
+    def load_index(self, flight_id: str, index_path: str) -> bool:
+        pass
+
+    @abstractmethod
+    def retrieve_candidate_tiles_for_chunk(self, chunk_images: List[np.ndarray], top_k: int) -> List[TileCandidate]:
+        pass
+
+    @abstractmethod
+    def compute_chunk_descriptor(self, chunk_images: List[np.ndarray]) -> np.ndarray:
+        pass
+
+
+class GlobalPlaceRecognition(IGlobalPlaceRecognition):
+    """AnyLoc-VLAD-DINOv2 coarse localisation component — sprint 1 GPR baseline.
+
+    GPR-01: load_index() tries to open a real Faiss .index file; falls back to
+            a NumPy L2 mock when the file is missing or Faiss is not installed.
+    GPR-02: Descriptor computed via DINOv2 engine (TRT FP16 on Jetson, Mock on
+            dev/CI). INT8 quantization is disabled — broken for ViT on Jetson
+            (NVIDIA/TRT#4348, facebookresearch/dinov2#489).
+    GPR-03: Candidates ranked by descriptor similarity (L2 → converted to [0,1]).
+
+    Selected over NetVLAD (deprecated, −2.4% R@1 on MSLS 2024) and SuperPoint+
+    LightGlue (unvalidated for cross-view UAV↔satellite gap at sprint 1).
+    Stage 2 evaluation: SP+LG+FAISS per _docs/03_backlog/stage2_ideas/.
+    Long-term target: EigenPlaces (ICCV 2023) — cleaner ONNX export.
+
+    Ref: docs/superpowers/specs/2026-04-18-oss-stack-tech-audit-design.md §2.3
+    """
+
+    _DIM = 4096  # DINOv2 VLAD descriptor dimension
+
+    def __init__(self, model_manager: IModelManager):
+        self.model_manager = model_manager
+
+        # Index storage — one of: Faiss index OR numpy matrix
+        self._faiss_index = None          # faiss.IndexFlatIP or similar
+        self._np_descriptors: np.ndarray | None = None   # (N, DIM) fallback
+        self._metadata: Dict[int, dict] = {}
+        self._is_loaded = False
+
+    # ------------------------------------------------------------------
+    # GPR-02: Descriptor extraction via DINOv2
+    # ------------------------------------------------------------------
+
+    def compute_location_descriptor(self, image: np.ndarray) -> np.ndarray:
+        """Run DINOv2 inference and return an L2-normalised descriptor."""
+        engine = self.model_manager.get_inference_engine("DINOv2")
+        desc = engine.infer(image)
+        norm = np.linalg.norm(desc)
+        return desc / max(norm, 1e-12)
+
+    def compute_chunk_descriptor(self, chunk_images: List[np.ndarray]) -> np.ndarray:
+        """Mean-aggregate per-frame DINOv2 descriptors for a chunk."""
+        if not chunk_images:
+            return np.zeros(self._DIM, dtype=np.float32)
+        descs = [self.compute_location_descriptor(img) for img in chunk_images]
+        agg = np.mean(descs, axis=0)
+        return agg / max(np.linalg.norm(agg), 1e-12)
+
+    # ------------------------------------------------------------------
+    # GPR-01: Index loading
+    # ------------------------------------------------------------------
+
+    def load_index(self, flight_id: str, index_path: str) -> bool:
+        """Load a Faiss descriptor index from disk (GPR-01).
+
+        Falls back to a NumPy random-vector mock when:
+          - `index_path` does not exist, OR
+          - Faiss is not installed (dev/CI without faiss-cpu).
+        """
+        logger.info("Loading GPR index for flight=%s path=%s", flight_id, index_path)
+
+        # Try real Faiss load ------------------------------------------------
+        if _FAISS_AVAILABLE and os.path.isfile(index_path):
+            try:
+                self._faiss_index = _faiss.read_index(index_path)
+                # Load companion metadata JSON if present
+                meta_path = os.path.splitext(index_path)[0] + "_meta.json"
+                if os.path.isfile(meta_path):
+                    with open(meta_path) as f:
+                        raw = json.load(f)
+                    self._metadata = {int(k): v for k, v in raw.items()}
+                    # Deserialise GPSPoint / TileBounds from dicts
+                    for idx, m in self._metadata.items():
+                        if isinstance(m.get("gps_center"), dict):
+                            m["gps_center"] = GPSPoint(**m["gps_center"])
+                        if isinstance(m.get("bounds"), dict):
+                            bounds_d = m["bounds"]
+                            for corner in ("nw", "ne", "sw", "se", "center"):
+                                if isinstance(bounds_d.get(corner), dict):
+                                    bounds_d[corner] = GPSPoint(**bounds_d[corner])
+                            m["bounds"] = TileBounds(**bounds_d)
+                else:
+                    self._metadata = self._generate_stub_metadata(self._faiss_index.ntotal)
+                self._is_loaded = True
+                logger.info("Faiss index loaded: %d vectors", self._faiss_index.ntotal)
+                return True
+            except Exception as exc:
+                logger.warning("Faiss load failed (%s) — falling back to numpy mock", exc)
+
+        # NumPy mock fallback ------------------------------------------------
+        logger.info("GPR: using numpy mock index (dev/CI mode)")
+        db_size = 1000
+        vecs = np.random.rand(db_size, self._DIM).astype(np.float32)
+        norms = np.linalg.norm(vecs, axis=1, keepdims=True)
+        self._np_descriptors = vecs / np.maximum(norms, 1e-12)
+        self._metadata = self._generate_stub_metadata(db_size)
+        self._is_loaded = True
+        return True
+
+    @staticmethod
+    def _generate_stub_metadata(n: int) -> Dict[int, dict]:
+        """Generate placeholder tile metadata for dev/CI mock index."""
+        meta: Dict[int, dict] = {}
+        for i in range(n):
+            meta[i] = {
+                "tile_id": f"tile_{i:06d}",
+                "gps_center": GPSPoint(lat=49.0 + np.random.rand(), lon=32.0 + np.random.rand()),
+                "bounds": TileBounds(
+                    nw=GPSPoint(lat=49.1, lon=32.0),
+                    ne=GPSPoint(lat=49.1, lon=32.1),
+                    sw=GPSPoint(lat=49.0, lon=32.0),
+                    se=GPSPoint(lat=49.0, lon=32.1),
+                    center=GPSPoint(lat=49.05, lon=32.05),
+                    gsd=0.6,
+                ),
+            }
+        return meta
+
+    # ------------------------------------------------------------------
+    # GPR-03: Similarity search ranked by descriptor distance
+    # ------------------------------------------------------------------
+
+    def query_database(self, descriptor: np.ndarray, top_k: int) -> List[DatabaseMatch]:
+        """Search the index for the top-k most similar tiles.
+
+        Uses Faiss when loaded, numpy L2 otherwise.
+        Results are sorted by ascending L2 distance (= descending similarity).
+        """
+        if not self._is_loaded:
+            logger.error("GPR index not loaded — call load_index() first.")
+            return []
+
+        q = descriptor.astype(np.float32).reshape(1, -1)
+
+        # Faiss path
+        if self._faiss_index is not None:
+            try:
+                distances, indices = self._faiss_index.search(q, top_k)
+                results = []
+                for dist, idx in zip(distances[0], indices[0]):
+                    if idx < 0:
+                        continue
+                    sim = 1.0 / (1.0 + float(dist))
+                    meta = self._metadata.get(int(idx), {"tile_id": f"tile_{idx}"})
+                    results.append(DatabaseMatch(
+                        index=int(idx),
+                        tile_id=meta.get("tile_id", str(idx)),
+                        distance=float(dist),
+                        similarity_score=sim,
+                    ))
+                return results
+            except Exception as exc:
+                logger.warning("Faiss search failed: %s", exc)
+
+        # NumPy path
+        if self._np_descriptors is None:
+            return []
+        diff = self._np_descriptors - q  # (N, DIM)
+        distances = np.sum(diff ** 2, axis=1)
+        top_indices = np.argsort(distances)[:top_k]
+
+        results = []
+        for idx in top_indices:
+            dist = float(distances[idx])
+            sim = 1.0 / (1.0 + dist)
+            meta = self._metadata.get(int(idx), {"tile_id": f"tile_{idx}"})
+            results.append(DatabaseMatch(
+                index=int(idx),
+                tile_id=meta.get("tile_id", str(idx)),
+                distance=dist,
+                similarity_score=sim,
+            ))
+        return results
+
+    def rank_candidates(self, candidates: List[TileCandidate]) -> List[TileCandidate]:
+        """Sort candidates by descriptor similarity (descending) — GPR-03."""
+        return sorted(candidates, key=lambda c: c.similarity_score, reverse=True)
+
+    def _matches_to_candidates(self, matches: List[DatabaseMatch]) -> List[TileCandidate]:
+        candidates = []
+        for rank, match in enumerate(matches, 1):
+            meta = self._metadata.get(match.index, {})
+            gps = meta.get("gps_center", GPSPoint(lat=49.0, lon=32.0))
+            bounds = meta.get("bounds", TileBounds(
+                nw=GPSPoint(lat=49.1, lon=32.0), ne=GPSPoint(lat=49.1, lon=32.1),
+                sw=GPSPoint(lat=49.0, lon=32.0), se=GPSPoint(lat=49.0, lon=32.1),
+                center=GPSPoint(lat=49.05, lon=32.05), gsd=0.6,
+            ))
+            candidates.append(TileCandidate(
+                tile_id=match.tile_id,
+                gps_center=gps,
+                bounds=bounds,
+                similarity_score=match.similarity_score,
+                rank=rank,
+            ))
+        return self.rank_candidates(candidates)
+
+    def retrieve_candidate_tiles(self, image: np.ndarray, top_k: int = 5) -> List[TileCandidate]:
+        desc = self.compute_location_descriptor(image)
+        matches = self.query_database(desc, top_k)
+        return self._matches_to_candidates(matches)
+
+    def retrieve_candidate_tiles_for_chunk(
+        self, chunk_images: List[np.ndarray], top_k: int = 5
+    ) -> List[TileCandidate]:
+        desc = self.compute_chunk_descriptor(chunk_images)
+        matches = self.query_database(desc, top_k)
+        return self._matches_to_candidates(matches)

src/gps_denied/components/gpr/protocol.py

@@ -0,0 +1,43 @@
+"""Protocol surface for the GPR component (ARCH-05).
+
+Phase 1: mirrors ``IGlobalPlaceRecognition`` from ``core/gpr.py``.
+Adapters move here in Plan 05 (GPR).
+"""
+from __future__ import annotations
+
+from typing import List, Protocol, runtime_checkable
+
+import numpy as np
+
+from gps_denied.schemas.gpr import DatabaseMatch, TileCandidate
+
+
+@runtime_checkable
+class GlobalPlaceRecognition(Protocol):
+    """Coarse localisation surface (mirrors IGlobalPlaceRecognition)."""
+
+    def retrieve_candidate_tiles(
+        self, image: np.ndarray, top_k: int
+    ) -> List[TileCandidate]: ...
+
+    def compute_location_descriptor(self, image: np.ndarray) -> np.ndarray: ...
+
+    def query_database(
+        self, descriptor: np.ndarray, top_k: int
+    ) -> List[DatabaseMatch]: ...
+
+    def rank_candidates(
+        self, candidates: List[TileCandidate]
+    ) -> List[TileCandidate]: ...
+
+    def load_index(self, flight_id: str, index_path: str) -> bool: ...
+
+    def retrieve_candidate_tiles_for_chunk(
+        self, chunk_images: List[np.ndarray], top_k: int
+    ) -> List[TileCandidate]: ...
+
+    def compute_chunk_descriptor(self, chunk_images: List[np.ndarray]) -> np.ndarray: ...
+
+
+# Backwards-compat alias.
+IGlobalPlaceRecognition = GlobalPlaceRecognition

src/gps_denied/components/mavlink_io/__init__.py

@@ -0,0 +1,19 @@
+from .protocol import MAVLinkBridgeProtocol
+from .pymavlink_bridge import (
+    MAVLinkBridge,
+    _PYMAVLINK_AVAILABLE,
+    _unix_to_gps_time,
+    _confidence_to_fix_type,
+    _eskf_to_gps_input,
+)
+from .mock_mavlink import MockMAVConnection
+
+__all__ = [
+    "MAVLinkBridgeProtocol",
+    "MAVLinkBridge",
+    "_PYMAVLINK_AVAILABLE",
+    "_unix_to_gps_time",
+    "_confidence_to_fix_type",
+    "_eskf_to_gps_input",
+    "MockMAVConnection",
+]

src/gps_denied/components/mavlink_io/mock_mavlink.py

@@ -0,0 +1,30 @@
+"""No-op MAVLink connection used in dev/CI (pymavlink absent).
+
+Extracted from gps_denied/core/mavlink.py (Plan 01-06).
+The legacy import path (gps_denied.core.mavlink) re-exports this class.
+"""
+
+from __future__ import annotations
+
+
+class MockMAVConnection:
+    """No-op MAVLink connection used when pymavlink is not installed."""
+
+    def __init__(self):
+        self._sent: list[dict] = []
+        self._rx_messages: list = []
+
+    def mav(self):
+        return self
+
+    def gps_input_send(self, *args, **kwargs) -> None:  # noqa: D102
+        self._sent.append({"type": "GPS_INPUT", "args": args, "kwargs": kwargs})
+
+    def named_value_float_send(self, *args, **kwargs) -> None:  # noqa: D102
+        self._sent.append({"type": "NAMED_VALUE_FLOAT", "args": args, "kwargs": kwargs})
+
+    def recv_match(self, type=None, blocking=False, timeout=0.1):  # noqa: D102
+        return None
+
+    def close(self) -> None:
+        pass

src/gps_denied/components/mavlink_io/protocol.py

@@ -0,0 +1,39 @@
+"""Protocol surface for the MAVLink I/O component (ARCH-05).
+
+Phase 1: mirrors the concrete ``MAVLinkBridge`` public surface from
+``core/mavlink.py`` (no ABC today). Adapters move here in Plan 07
+(mavlink_io); private helpers ``_confidence_to_fix_type`` and
+``_eskf_to_gps_input`` MUST stay re-exported from the old path.
+"""
+from __future__ import annotations
+
+from typing import Callable, Optional, Protocol, runtime_checkable
+
+from gps_denied.schemas import GPSPoint
+from gps_denied.schemas.eskf import ESKFState, IMUMeasurement
+from gps_denied.schemas.mavlink import GPSInputMessage, RelocalizationRequest
+
+
+@runtime_checkable
+class MAVLinkBridgeProtocol(Protocol):
+    """Public surface of the MAVLink GPS_INPUT/IMU/telemetry bridge."""
+
+    def set_imu_callback(
+        self, cb: Callable[[IMUMeasurement], None]
+    ) -> None: ...
+
+    def set_reloc_callback(
+        self, cb: Callable[[RelocalizationRequest], None]
+    ) -> None: ...
+
+    def update_state(self, state: ESKFState, altitude_m: float = 0.0) -> None: ...
+
+    def notify_satellite_correction(self) -> None: ...
+
+    def update_drift_estimate(self, drift_m: float) -> None: ...
+
+    async def start(self, origin: GPSPoint) -> None: ...
+
+    async def stop(self) -> None: ...
+
+    def build_gps_input(self) -> Optional[GPSInputMessage]: ...

src/gps_denied/components/mavlink_io/pymavlink_bridge.py

@@ -0,0 +1,455 @@
+"""MAVLink I/O Bridge — concrete pymavlink implementation (Phase 1 refactor).
+
+Extracted from gps_denied/core/mavlink.py (Plan 01-06).
+The legacy import path (gps_denied.core.mavlink) re-exports everything here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import math
+import time
+from typing import Callable, Optional
+
+import numpy as np
+
+from gps_denied.schemas import GPSPoint
+from gps_denied.schemas.eskf import ConfidenceTier, ESKFState, IMUMeasurement
+from gps_denied.schemas.mavlink import (
+    GPSInputMessage,
+    RelocalizationRequest,
+    TelemetryMessage,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# pymavlink conditional import
+# ---------------------------------------------------------------------------
+try:
+    from pymavlink import mavutil as _mavutil  # type: ignore
+    _PYMAVLINK_AVAILABLE = True
+    logger.info("pymavlink available — real MAVLink connection enabled")
+except ImportError:
+    _mavutil = None  # type: ignore
+    _PYMAVLINK_AVAILABLE = False
+    logger.info("pymavlink not available — using MockMAVConnection (dev/CI mode)")
+
+# GPS epoch offset from Unix epoch (seconds)
+_GPS_EPOCH_OFFSET = 315_964_800
+
+
+# ---------------------------------------------------------------------------
+# GPS time helpers (MAV-02)
+# ---------------------------------------------------------------------------
+
+def _unix_to_gps_time(unix_s: float) -> tuple[int, int]:
+    """Convert Unix timestamp to (GPS_week, GPS_ms_of_week)."""
+    gps_s = unix_s - _GPS_EPOCH_OFFSET
+    gps_s = max(0.0, gps_s)
+    week = int(gps_s // (7 * 86400))
+    ms_of_week = int((gps_s % (7 * 86400)) * 1000)
+    return week, ms_of_week
+
+
+def _confidence_to_fix_type(confidence: ConfidenceTier) -> int:
+    """Map ESKF confidence tier to GPS_INPUT fix_type (MAV-02)."""
+    return {
+        ConfidenceTier.HIGH: 3,    # 3D fix
+        ConfidenceTier.MEDIUM: 3,  # 3D fix (VO tracking valid per solution.md)
+        ConfidenceTier.LOW: 0,
+        ConfidenceTier.FAILED: 0,
+    }.get(confidence, 0)
+
+
+def _eskf_to_gps_input(
+    state: ESKFState,
+    origin: GPSPoint,
+    altitude_m: float = 0.0,
+) -> GPSInputMessage:
+    """Build a GPSInputMessage from ESKF state (MAV-02).
+
+    Args:
+        state:       Current ESKF nominal state.
+        origin:      WGS84 ENU reference origin set at mission start.
+        altitude_m:  Barometric altitude in metres MSL (from FC telemetry).
+    """
+    # ENU → WGS84
+    east, north = state.position[0], state.position[1]
+    cos_lat = math.cos(math.radians(origin.lat))
+    lat_wgs84 = origin.lat + north / 111_319.5
+    lon_wgs84 = origin.lon + east / (cos_lat * 111_319.5)
+
+    # Velocity: ENU → NED
+    vn = state.velocity[1]   # North = ENU[1]
+    ve = state.velocity[0]   # East  = ENU[0]
+    vd = -state.velocity[2]  # Down  = -Up
+
+    # Accuracy from covariance (position block = rows 0-2, cols 0-2)
+    cov_pos = state.covariance[:3, :3]
+    sigma_h = math.sqrt(max(0.0, cov_pos[0, 0] + cov_pos[1, 1]))
+    sigma_v = math.sqrt(max(0.0, cov_pos[2, 2]))
+    speed_sigma = math.sqrt(max(0.0, (state.covariance[3, 3] + state.covariance[4, 4]) / 2.0))
+
+    # Synthesised hdop/vdop (hdop ≈ σ_h / 5 maps to typical DOP scale)
+    hdop = max(0.1, sigma_h / 5.0)
+    vdop = max(0.1, sigma_v / 5.0)
+
+    fix_type = _confidence_to_fix_type(state.confidence)
+
+    now = state.timestamp if state.timestamp > 0 else time.time()
+    week, week_ms = _unix_to_gps_time(now)
+
+    return GPSInputMessage(
+        time_usec=int(now * 1_000_000),
+        time_week=week,
+        time_week_ms=week_ms,
+        fix_type=fix_type,
+        lat=int(lat_wgs84 * 1e7),
+        lon=int(lon_wgs84 * 1e7),
+        alt=altitude_m,
+        hdop=round(hdop, 2),
+        vdop=round(vdop, 2),
+        vn=round(vn, 4),
+        ve=round(ve, 4),
+        vd=round(vd, 4),
+        speed_accuracy=round(speed_sigma, 2),
+        horiz_accuracy=round(sigma_h, 2),
+        vert_accuracy=round(sigma_v, 2),
+        satellites_visible=10,
+    )
+
+
+# ---------------------------------------------------------------------------
+# MAVLinkBridge
+# ---------------------------------------------------------------------------
+
+class MAVLinkBridge:
+    """Full MAVLink I/O bridge.
+
+    Usage::
+
+        bridge = MAVLinkBridge(connection_string="serial:/dev/ttyTHS1:57600")
+        await bridge.start(origin_gps, eskf_instance)
+        # ... flight ...
+        await bridge.stop()
+    """
+
+    def __init__(
+        self,
+        connection_string: str = "udp:127.0.0.1:14550",
+        output_hz: float = 5.0,
+        telemetry_hz: float = 1.0,
+        max_consecutive_failures: int = 3,
+    ):
+        self.connection_string = connection_string
+        self.output_hz = output_hz
+        self.telemetry_hz = telemetry_hz
+        self.max_consecutive_failures = max_consecutive_failures
+
+        self._conn = None
+        self._origin: Optional[GPSPoint] = None
+        self._altitude_m: float = 0.0
+
+        # State shared between loops
+        self._last_state: Optional[ESKFState] = None
+        self._last_gps: Optional[GPSPoint] = None
+        self._consecutive_failures: int = 0
+        self._frames_since_sat: int = 0
+        self._drift_estimate_m: float = 0.0
+
+        # Callbacks
+        self._on_imu: Optional[Callable[[IMUMeasurement], None]] = None
+        self._on_reloc_request: Optional[Callable[[RelocalizationRequest], None]] = None
+
+        # asyncio tasks
+        self._tasks: list[asyncio.Task] = []
+        self._running = False
+
+        # Diagnostics
+        self._sent_count: int = 0
+        self._recv_imu_count: int = 0
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def set_imu_callback(self, cb: Callable[[IMUMeasurement], None]) -> None:
+        """Register callback invoked for each received IMU packet (MAV-03)."""
+        self._on_imu = cb
+
+    def set_reloc_callback(self, cb: Callable[[RelocalizationRequest], None]) -> None:
+        """Register callback invoked when re-localisation is requested (MAV-04)."""
+        self._on_reloc_request = cb
+
+    def update_state(self, state: ESKFState, altitude_m: float = 0.0) -> None:
+        """Push a fresh ESKF state snapshot (called by processor per frame)."""
+        self._last_state = state
+        self._altitude_m = altitude_m
+        if state.confidence in (ConfidenceTier.HIGH, ConfidenceTier.MEDIUM):
+            # Position available
+            self._consecutive_failures = 0
+        else:
+            self._consecutive_failures += 1
+
+    def notify_satellite_correction(self) -> None:
+        """Reset frames_since_sat counter after a satellite match."""
+        self._frames_since_sat = 0
+
+    def update_drift_estimate(self, drift_m: float) -> None:
+        """Update running drift estimate (metres) for telemetry."""
+        self._drift_estimate_m = drift_m
+
+    async def start(self, origin: GPSPoint) -> None:
+        """Open the connection and launch background I/O coroutines."""
+        self._origin = origin
+        self._running = True
+        self._conn = self._open_connection()
+        self._tasks = [
+            asyncio.create_task(self._gps_output_loop(), name="mav_gps_output"),
+            asyncio.create_task(self._imu_receive_loop(), name="mav_imu_input"),
+            asyncio.create_task(self._telemetry_loop(), name="mav_telemetry"),
+        ]
+        logger.info("MAVLinkBridge started (conn=%s, %g Hz)", self.connection_string, self.output_hz)
+
+    async def stop(self) -> None:
+        """Cancel background tasks and close connection."""
+        self._running = False
+        for t in self._tasks:
+            t.cancel()
+        await asyncio.gather(*self._tasks, return_exceptions=True)
+        self._tasks.clear()
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+        logger.info("MAVLinkBridge stopped. sent=%d imu_rx=%d",
+                    self._sent_count, self._recv_imu_count)
+
+    def build_gps_input(self) -> Optional[GPSInputMessage]:
+        """Build GPSInputMessage from current ESKF state (public, for testing)."""
+        if self._last_state is None or self._origin is None:
+            return None
+        return _eskf_to_gps_input(self._last_state, self._origin, self._altitude_m)
+
+    # ------------------------------------------------------------------
+    # MAV-01/02: GPS_INPUT output loop
+    # ------------------------------------------------------------------
+
+    async def _gps_output_loop(self) -> None:
+        """Send GPS_INPUT at output_hz.  MAV-01 / MAV-02."""
+        interval = 1.0 / self.output_hz
+        while self._running:
+            try:
+                msg = self.build_gps_input()
+                if msg is not None:
+                    self._send_gps_input(msg)
+                    self._sent_count += 1
+
+                    # MAV-04: check consecutive failures
+                    if self._consecutive_failures >= self.max_consecutive_failures:
+                        self._send_reloc_request()
+            except Exception as exc:
+                logger.warning("GPS output loop error: %s", exc)
+            await asyncio.sleep(interval)
+
+    def _send_gps_input(self, msg: GPSInputMessage) -> None:
+        if self._conn is None:
+            return
+        # Import MockMAVConnection locally to avoid circular import
+        from gps_denied.components.mavlink_io.mock_mavlink import MockMAVConnection
+        try:
+            if _PYMAVLINK_AVAILABLE and not isinstance(self._conn, MockMAVConnection):
+                self._conn.mav.gps_input_send(
+                    msg.time_usec,
+                    msg.gps_id,
+                    msg.ignore_flags,
+                    msg.time_week_ms,
+                    msg.time_week,
+                    msg.fix_type,
+                    msg.lat,
+                    msg.lon,
+                    msg.alt,
+                    msg.hdop,
+                    msg.vdop,
+                    msg.vn,
+                    msg.ve,
+                    msg.vd,
+                    msg.speed_accuracy,
+                    msg.horiz_accuracy,
+                    msg.vert_accuracy,
+                    msg.satellites_visible,
+                )
+            else:
+                # MockMAVConnection records the call
+                self._conn.gps_input_send(
+                    time_usec=msg.time_usec,
+                    fix_type=msg.fix_type,
+                    lat=msg.lat,
+                    lon=msg.lon,
+                )
+        except Exception as exc:
+            logger.error("Failed to send GPS_INPUT: %s", exc)
+
+    # ------------------------------------------------------------------
+    # MAV-03: IMU receive loop
+    # ------------------------------------------------------------------
+
+    async def _imu_receive_loop(self) -> None:
+        """Receive ATTITUDE/RAW_IMU and invoke ESKF callback.  MAV-03."""
+        while self._running:
+            try:
+                raw = self._recv_imu()
+                if raw is not None:
+                    self._recv_imu_count += 1
+                    if self._on_imu:
+                        self._on_imu(raw)
+            except Exception as exc:
+                logger.warning("IMU receive loop error: %s", exc)
+            await asyncio.sleep(0.01)  # poll at ~100 Hz; blocks throttled by recv_match timeout
+
+    def _recv_imu(self) -> Optional[IMUMeasurement]:
+        """Try to read one IMU packet from the MAVLink connection."""
+        if self._conn is None:
+            return None
+        from gps_denied.components.mavlink_io.mock_mavlink import MockMAVConnection
+        if isinstance(self._conn, MockMAVConnection):
+            return None  # mock produces no IMU traffic
+
+        try:
+            msg = self._conn.recv_match(type=["RAW_IMU", "SCALED_IMU2"], blocking=False, timeout=0.01)
+            if msg is None:
+                return None
+            t = time.time()
+            # RAW_IMU fields (all in milli-g / milli-rad/s — convert to SI)
+            ax = getattr(msg, "xacc", 0) * 9.80665e-3   # milli-g → m/s²
+            ay = getattr(msg, "yacc", 0) * 9.80665e-3
+            az = getattr(msg, "zacc", 0) * 9.80665e-3
+            gx = getattr(msg, "xgyro", 0) * 1e-3        # milli-rad/s → rad/s
+            gy = getattr(msg, "ygyro", 0) * 1e-3
+            gz = getattr(msg, "zgyro", 0) * 1e-3
+            return IMUMeasurement(
+                accel=np.array([ax, ay, az]),
+                gyro=np.array([gx, gy, gz]),
+                timestamp=t,
+            )
+        except Exception as exc:
+            logger.debug("IMU recv error: %s", exc)
+            return None
+
+    # ------------------------------------------------------------------
+    # MAV-04: Re-localisation request
+    # ------------------------------------------------------------------
+
+    def _send_reloc_request(self) -> None:
+        """Send NAMED_VALUE_FLOAT re-localisation beacon (MAV-04)."""
+        req = self._build_reloc_request()
+        if self._on_reloc_request:
+            self._on_reloc_request(req)
+        if self._conn is None:
+            return
+        from gps_denied.components.mavlink_io.mock_mavlink import MockMAVConnection
+        try:
+            t_boot_ms = int((time.time() % (2**32 / 1000)) * 1000)
+            for name, value in [
+                ("RELOC_LAT", float(req.last_lat or 0.0)),
+                ("RELOC_LON", float(req.last_lon or 0.0)),
+                ("RELOC_UNC", float(req.uncertainty_m)),
+            ]:
+                if _PYMAVLINK_AVAILABLE and not isinstance(self._conn, MockMAVConnection):
+                    self._conn.mav.named_value_float_send(
+                        t_boot_ms,
+                        name.encode()[:10],
+                        value,
+                    )
+                else:
+                    self._conn.named_value_float_send(time=t_boot_ms, name=name, value=value)
+            logger.warning("Re-localisation request sent (failures=%d)", self._consecutive_failures)
+        except Exception as exc:
+            logger.error("Failed to send reloc request: %s", exc)
+
+    def _build_reloc_request(self) -> RelocalizationRequest:
+        last_lat, last_lon = None, None
+        if self._last_state is not None and self._origin is not None:
+            east = self._last_state.position[0]
+            north = self._last_state.position[1]
+            cos_lat = math.cos(math.radians(self._origin.lat))
+            last_lat = self._origin.lat + north / 111_319.5
+            last_lon = self._origin.lon + east / (cos_lat * 111_319.5)
+            cov = self._last_state.covariance[:2, :2]
+            sigma_h = math.sqrt(max(0.0, (cov[0, 0] + cov[1, 1]) / 2.0))
+        else:
+            sigma_h = 500.0
+        return RelocalizationRequest(
+            last_lat=last_lat,
+            last_lon=last_lon,
+            uncertainty_m=max(sigma_h * 3.0, 50.0),
+            consecutive_failures=self._consecutive_failures,
+        )
+
+    # ------------------------------------------------------------------
+    # MAV-05: Telemetry loop
+    # ------------------------------------------------------------------
+
+    async def _telemetry_loop(self) -> None:
+        """Send confidence + drift at 1 Hz.  MAV-05."""
+        interval = 1.0 / self.telemetry_hz
+        while self._running:
+            try:
+                self._send_telemetry()
+                self._frames_since_sat += 1
+            except Exception as exc:
+                logger.warning("Telemetry loop error: %s", exc)
+            await asyncio.sleep(interval)
+
+    def _send_telemetry(self) -> None:
+        if self._last_state is None or self._conn is None:
+            return
+
+        from gps_denied.components.mavlink_io.mock_mavlink import MockMAVConnection
+        fix_type = _confidence_to_fix_type(self._last_state.confidence)
+        confidence_score = {
+            ConfidenceTier.HIGH: 1.0,
+            ConfidenceTier.MEDIUM: 0.6,
+            ConfidenceTier.LOW: 0.2,
+            ConfidenceTier.FAILED: 0.0,
+        }.get(self._last_state.confidence, 0.0)
+
+        telemetry = TelemetryMessage(
+            confidence_score=confidence_score,
+            drift_estimate_m=self._drift_estimate_m,
+            fix_type=fix_type,
+            frames_since_sat=self._frames_since_sat,
+        )
+
+        t_boot_ms = int((time.time() % (2**32 / 1000)) * 1000)
+        for name, value in [
+            ("CONF_SCORE", telemetry.confidence_score),
+            ("DRIFT_M", telemetry.drift_estimate_m),
+        ]:
+            try:
+                if _PYMAVLINK_AVAILABLE and not isinstance(self._conn, MockMAVConnection):
+                    self._conn.mav.named_value_float_send(
+                        t_boot_ms,
+                        name.encode()[:10],
+                        float(value),
+                    )
+                else:
+                    self._conn.named_value_float_send(time=t_boot_ms, name=name, value=float(value))
+            except Exception as exc:
+                logger.debug("Telemetry send error: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Connection factory
+    # ------------------------------------------------------------------
+
+    def _open_connection(self):
+        from gps_denied.components.mavlink_io.mock_mavlink import MockMAVConnection
+        if _PYMAVLINK_AVAILABLE:
+            try:
+                conn = _mavutil.mavlink_connection(self.connection_string)
+                logger.info("MAVLink connection opened: %s", self.connection_string)
+                return conn
+            except Exception as exc:
+                logger.warning("Cannot open MAVLink connection (%s) — using mock", exc)
+        return MockMAVConnection()

src/gps_denied/components/safety_state/protocol.py

@@ -0,0 +1,44 @@
+"""Protocol surface for the safety_state component (Phase 3, SAFE-01..06).
+
+Phase 1: stub only — the SafetyAnchorStateMachine becomes the
+authoritative source_label owner per SAFE-01 in Phase 3.
+"""
+from __future__ import annotations
+
+from enum import Enum
+from typing import Protocol, runtime_checkable
+
+from gps_denied.hot_types.position_estimate import PositionEstimate
+from gps_denied.hot_types.satellite_anchor import SatelliteAnchor
+
+
+class SourceLabel(str, Enum):
+    """Authoritative label for the provenance of a PositionEstimate (SAFE-01)."""
+
+    SATELLITE_ANCHORED = "satellite_anchored"
+    VO_EXTRAPOLATED = "vo_extrapolated"
+    DEAD_RECKONED = "dead_reckoned"
+
+
+@runtime_checkable
+class SafetyAnchorStateMachine(Protocol):
+    """Authoritative source_label owner per SAFE-01. Filled in Phase 3."""
+
+    @property
+    def source_label(self) -> SourceLabel: ...
+
+    @property
+    def anchor_age_ms(self) -> float: ...
+
+    @property
+    def can_persist_tile(self) -> bool: ...
+
+    def on_anchor_accepted(self, anchor: SatelliteAnchor) -> None: ...
+
+    def on_anchor_rejected(self, reason: str) -> None: ...
+
+    def on_vo_update(self, timestamp: float) -> None: ...
+
+    def on_visual_blackout(self) -> None: ...
+
+    def annotate(self, estimate: PositionEstimate) -> PositionEstimate: ...

src/gps_denied/components/satellite_matcher/__init__.py

@@ -0,0 +1,13 @@
+"""satellite_matcher component public API."""
+
+from .local_tile_loader import SatelliteDataManager
+from .metric_refinement import MetricRefinement
+from .protocol import IMetricRefinement, MetricRefiner, SatelliteTileLoader
+
+__all__ = [
+    "SatelliteDataManager",
+    "MetricRefinement",
+    "IMetricRefinement",
+    "MetricRefiner",
+    "SatelliteTileLoader",
+]

src/gps_denied/components/satellite_matcher/local_tile_loader.py

@@ -0,0 +1,283 @@
+"""Local-disk tile loader (SAT-01/02). Phase 1 home of the existing SatelliteDataManager impl."""
+
+import hashlib
+import logging
+import math
+import os
+from concurrent.futures import ThreadPoolExecutor
+
+import cv2
+import numpy as np
+
+from gps_denied.schemas import GPSPoint
+from gps_denied.schemas.satellite import TileBounds, TileCoords
+from gps_denied.utils import mercator
+
+
+class SatelliteDataManager:
+    """Manages satellite tiles from a local pre-loaded directory.
+
+    Directory layout (SAT-01):
+        {tile_dir}/{zoom}/{x}/{y}.png   — standard Web Mercator slippy-map layout
+
+    No live HTTP requests are made during flight.  A separate offline tooling step
+    downloads and stores tiles before the mission.
+    """
+
+    _logger = logging.getLogger(__name__)
+
+    def __init__(
+        self,
+        tile_dir: str = ".satellite_tiles",
+        cache_dir: str = ".satellite_cache",
+        max_size_gb: float = 10.0,
+    ):
+        self.tile_dir = tile_dir
+        self.thread_pool = ThreadPoolExecutor(max_workers=4)
+        # In-memory LRU for hot tiles (avoids repeated disk reads)
+        self._mem_cache: dict[str, np.ndarray] = {}
+        self._mem_cache_max = 256
+        # SHA-256 manifest for tile integrity (якщо файл існує)
+        self._manifest: dict[str, str] = self._load_manifest()
+
+    # ------------------------------------------------------------------
+    # SAT-01: Local tile reads (no HTTP)
+    # ------------------------------------------------------------------
+
+    def _load_manifest(self) -> dict[str, str]:
+        """Завантажити SHA-256 manifest з tile_dir/manifest.sha256."""
+        path = os.path.join(self.tile_dir, "manifest.sha256")
+        if not os.path.isfile(path):
+            return {}
+        manifest: dict[str, str] = {}
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                parts = line.split(maxsplit=1)
+                if len(parts) == 2:
+                    manifest[parts[1].strip()] = parts[0].strip()
+        return manifest
+
+    def _verify_tile_integrity(self, rel_path: str, file_path: str) -> bool:
+        """Перевірити SHA-256 тайла проти manifest (якщо manifest існує)."""
+        if not self._manifest:
+            return True  # без manifest — пропускаємо
+        expected = self._manifest.get(rel_path)
+        if expected is None:
+            return True  # тайл не в manifest — OK
+        sha = hashlib.sha256()
+        with open(file_path, "rb") as f:
+            for chunk in iter(lambda: f.read(8192), b""):
+                sha.update(chunk)
+        actual = sha.hexdigest()
+        if actual != expected:
+            self._logger.warning("Tile integrity failed: %s (exp %s, got %s)",
+                                rel_path, expected[:12], actual[:12])
+            return False
+        return True
+
+    def load_local_tile(self, tile_coords: TileCoords) -> np.ndarray | None:
+        """Load a tile image from the local pre-loaded directory.
+
+        Expected path: {tile_dir}/{zoom}/{x}/{y}.png
+        Returns None if the file does not exist.
+        """
+        key = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}"
+        if key in self._mem_cache:
+            return self._mem_cache[key]
+
+        rel_path = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}.png"
+        path = os.path.join(self.tile_dir, rel_path)
+        if not os.path.isfile(path):
+            return None
+
+        if not self._verify_tile_integrity(rel_path, path):
+            return None  # тайл пошкоджений
+
+        img = cv2.imread(path, cv2.IMREAD_COLOR)
+        if img is None:
+            return None
+
+        # LRU eviction: drop oldest if full
+        if len(self._mem_cache) >= self._mem_cache_max:
+            oldest = next(iter(self._mem_cache))
+            del self._mem_cache[oldest]
+        self._mem_cache[key] = img
+        return img
+
+    def save_local_tile(self, tile_coords: TileCoords, image: np.ndarray) -> bool:
+        """Persist a tile to the local directory (used by offline pre-fetch tooling)."""
+        path = os.path.join(self.tile_dir, str(tile_coords.zoom),
+                            str(tile_coords.x), f"{tile_coords.y}.png")
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        ok, encoded = cv2.imencode(".png", image)
+        if not ok:
+            return False
+        with open(path, "wb") as f:
+            f.write(encoded.tobytes())
+        key = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}"
+        self._mem_cache[key] = image
+        return True
+
+    # ------------------------------------------------------------------
+    # SAT-02: Tile selection for ESKF position ± 3σ_horizontal
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _meters_to_degrees(meters: float, lat: float) -> tuple[float, float]:
+        """Convert a radius in metres to (Δlat°, Δlon°) at the given latitude."""
+        delta_lat = meters / 111_320.0
+        delta_lon = meters / (111_320.0 * math.cos(math.radians(lat)))
+        return delta_lat, delta_lon
+
+    def select_tiles_for_eskf_position(
+        self, gps: GPSPoint, sigma_h_m: float, zoom: int
+    ) -> list[TileCoords]:
+        """Return all tile coords covering the ESKF position ± 3σ_horizontal area.
+
+        Args:
+            gps:        ESKF best-estimate position.
+            sigma_h_m:  1-σ horizontal uncertainty in metres (from ESKF covariance).
+            zoom:       Web Mercator zoom level (18 recommended ≈ 0.6 m/px).
+        """
+        radius_m = 3.0 * sigma_h_m
+        dlat, dlon = self._meters_to_degrees(radius_m, gps.lat)
+
+        # Bounding box corners
+        lat_min, lat_max = gps.lat - dlat, gps.lat + dlat
+        lon_min, lon_max = gps.lon - dlon, gps.lon + dlon
+
+        # Convert corners to tile coords
+        tc_nw = mercator.latlon_to_tile(lat_max, lon_min, zoom)
+        tc_se = mercator.latlon_to_tile(lat_min, lon_max, zoom)
+
+        tiles: list[TileCoords] = []
+        for x in range(tc_nw.x, tc_se.x + 1):
+            for y in range(tc_nw.y, tc_se.y + 1):
+                tiles.append(TileCoords(x=x, y=y, zoom=zoom))
+        return tiles
+
+    def assemble_mosaic(
+        self,
+        tile_list: list[tuple[TileCoords, np.ndarray]],
+        target_size: int = 512,
+    ) -> tuple[np.ndarray, TileBounds] | None:
+        """Assemble a list of (TileCoords, image) pairs into a single mosaic.
+
+        Returns (mosaic_image, combined_bounds) or None if tile_list is empty.
+        The mosaic is resized to (target_size × target_size) for the matcher.
+        """
+        if not tile_list:
+            return None
+
+        xs = [tc.x for tc, _ in tile_list]
+        ys = [tc.y for tc, _ in tile_list]
+        zoom = tile_list[0][0].zoom
+
+        x_min, x_max = min(xs), max(xs)
+        y_min, y_max = min(ys), max(ys)
+
+        cols = x_max - x_min + 1
+        rows = y_max - y_min + 1
+
+        # Determine single-tile pixel size from first image
+        sample = tile_list[0][1]
+        th, tw = sample.shape[:2]
+
+        canvas = np.zeros((rows * th, cols * tw, 3), dtype=np.uint8)
+        for tc, img in tile_list:
+            col = tc.x - x_min
+            row = tc.y - y_min
+            h, w = img.shape[:2]
+            canvas[row * th: row * th + h, col * tw: col * tw + w] = img
+
+        mosaic = cv2.resize(canvas, (target_size, target_size), interpolation=cv2.INTER_AREA)
+
+        # Compute combined GPS bounds
+        nw_bounds = mercator.compute_tile_bounds(TileCoords(x=x_min, y=y_min, zoom=zoom))
+        se_bounds = mercator.compute_tile_bounds(TileCoords(x=x_max, y=y_max, zoom=zoom))
+        combined = TileBounds(
+            nw=nw_bounds.nw,
+            ne=GPSPoint(lat=nw_bounds.nw.lat, lon=se_bounds.se.lon),
+            sw=GPSPoint(lat=se_bounds.se.lat, lon=nw_bounds.nw.lon),
+            se=se_bounds.se,
+            center=GPSPoint(
+                lat=(nw_bounds.nw.lat + se_bounds.se.lat) / 2,
+                lon=(nw_bounds.nw.lon + se_bounds.se.lon) / 2,
+            ),
+            gsd=nw_bounds.gsd,
+        )
+        return mosaic, combined
+
+    def fetch_tiles_for_position(
+        self, gps: GPSPoint, sigma_h_m: float, zoom: int
+    ) -> tuple[np.ndarray, TileBounds] | None:
+        """High-level helper: select tiles + load + assemble mosaic.
+
+        Returns (mosaic, bounds) or None if no local tiles are available.
+        """
+        coords = self.select_tiles_for_eskf_position(gps, sigma_h_m, zoom)
+        loaded: list[tuple[TileCoords, np.ndarray]] = []
+        for tc in coords:
+            img = self.load_local_tile(tc)
+            if img is not None:
+                loaded.append((tc, img))
+        return self.assemble_mosaic(loaded) if loaded else None
+
+    # ------------------------------------------------------------------
+    # Cache helpers (backward-compat, also used for warm-path caching)
+    # ------------------------------------------------------------------
+
+    def cache_tile(self, flight_id: str, tile_coords: TileCoords, tile_data: np.ndarray) -> bool:
+        """Cache a tile image in memory (used by tests and offline tools)."""
+        key = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}"
+        self._mem_cache[key] = tile_data
+        return True
+
+    def get_cached_tile(self, flight_id: str, tile_coords: TileCoords) -> np.ndarray | None:
+        """Retrieve a cached tile from memory."""
+        key = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}"
+        return self._mem_cache.get(key)
+
+    # ------------------------------------------------------------------
+    # Tile math helpers
+    # ------------------------------------------------------------------
+
+    def get_tile_grid(self, center: TileCoords, grid_size: int) -> list[TileCoords]:
+        """Return grid_size tiles centered on center."""
+        if grid_size == 1:
+            return [center]
+
+        side = int(grid_size ** 0.5)
+        half = side // 2
+
+        coords: list[TileCoords] = []
+        for dy in range(-half, half + 1):
+            for dx in range(-half, half + 1):
+                coords.append(TileCoords(x=center.x + dx, y=center.y + dy, zoom=center.zoom))
+
+        if grid_size == 4:
+            coords = []
+            for dy in range(2):
+                for dx in range(2):
+                    coords.append(TileCoords(x=center.x + dx, y=center.y + dy, zoom=center.zoom))
+
+        return coords[:grid_size]
+
+    def expand_search_grid(self, center: TileCoords, current_size: int, new_size: int) -> list[TileCoords]:
+        """Return only the NEW tiles when expanding from current_size to new_size grid."""
+        old_set = {(c.x, c.y) for c in self.get_tile_grid(center, current_size)}
+        return [c for c in self.get_tile_grid(center, new_size) if (c.x, c.y) not in old_set]
+
+    def compute_tile_coords(self, lat: float, lon: float, zoom: int) -> TileCoords:
+        return mercator.latlon_to_tile(lat, lon, zoom)
+
+    def compute_tile_bounds(self, tile_coords: TileCoords) -> TileBounds:
+        return mercator.compute_tile_bounds(tile_coords)
+
+    def clear_flight_cache(self, flight_id: str) -> bool:
+        """Clear in-memory cache (flight scoping is tile-key-based)."""
+        self._mem_cache.clear()
+        return True

src/gps_denied/components/satellite_matcher/metric_refinement.py

@@ -0,0 +1,190 @@
+"""Metric Refinement implementation (SAT-03/04). Phase 1 home of MetricRefinement impl.
+
+SAT-03: GSD normalization — downsample camera frame to satellite resolution.
+SAT-04: RANSAC homography → WGS84 position; confidence = inlier_ratio.
+"""
+
+import logging
+from typing import List, Optional, Tuple
+
+import cv2
+import numpy as np
+
+from gps_denied.components.satellite_matcher.protocol import IMetricRefinement
+from gps_denied.core.models import IModelManager
+from gps_denied.schemas import GPSPoint
+from gps_denied.schemas.metric import AlignmentResult, ChunkAlignmentResult, Sim3Transform
+from gps_denied.schemas.satellite import TileBounds
+
+logger = logging.getLogger(__name__)
+
+
+class MetricRefinement(IMetricRefinement):
+    """LiteSAM/XFeat-based alignment with GSD normalization.
+
+    SAT-03: normalize_gsd() downsamples UAV frame to match satellite GSD before matching.
+    SAT-04: confidence is computed as inlier_count / total_correspondences (inlier ratio).
+    """
+
+    def __init__(self, model_manager: IModelManager):
+        self.model_manager = model_manager
+
+    # ------------------------------------------------------------------
+    # SAT-03: GSD normalization
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def normalize_gsd(
+        uav_image: np.ndarray,
+        uav_gsd_mpp: float,
+        sat_gsd_mpp: float,
+    ) -> np.ndarray:
+        """Resize UAV frame to match satellite GSD (meters-per-pixel).
+
+        Args:
+            uav_image:    Raw UAV camera frame.
+            uav_gsd_mpp:  UAV GSD in m/px (e.g. 0.159 at 600 m altitude).
+            sat_gsd_mpp:  Satellite tile GSD in m/px (e.g. 0.6 at zoom 18).
+
+        Returns:
+            Resized image.  If already coarser than satellite, returned unchanged.
+        """
+        if uav_gsd_mpp <= 0 or sat_gsd_mpp <= 0:
+            return uav_image
+        scale = uav_gsd_mpp / sat_gsd_mpp
+        if scale >= 1.0:
+            return uav_image  # UAV already coarser, nothing to do
+        h, w = uav_image.shape[:2]
+        new_w = max(1, int(w * scale))
+        new_h = max(1, int(h * scale))
+        return cv2.resize(uav_image, (new_w, new_h), interpolation=cv2.INTER_AREA)
+
+    def compute_homography(self, uav_image: np.ndarray, satellite_tile: np.ndarray) -> Optional[np.ndarray]:
+        engine = self.model_manager.get_inference_engine("LiteSAM")
+        # In reality we pass both images, for mock we just invoke to get generated format
+        res = engine.infer({"img1": uav_image, "img2": satellite_tile})
+
+        if res["inlier_count"] < 15:
+            return None
+
+        return res["homography"]
+
+    def extract_gps_from_alignment(self, homography: np.ndarray, tile_bounds: TileBounds, image_center: Tuple[int, int]) -> GPSPoint:
+        # UAV image center
+        cx, cy = image_center
+        # Apply homography
+        pt = np.array([cx, cy, 1.0])
+        # transformed = H * pt
+        transformed = homography @ pt
+        transformed = transformed / transformed[2]
+
+        tx, ty = transformed[0], transformed[1]
+
+        # Approximate GPS mapping using bounds
+        # ty maps to latitude (ty=0 is North, ty=Height is South)
+        # tx maps to longitude (tx=0 is West, tx=Width is East)
+        # We assume standard 256x256 tiles for this mock calculation
+        tile_size = 256.0
+
+        lat_span = tile_bounds.nw.lat - tile_bounds.sw.lat
+        lon_span = tile_bounds.ne.lon - tile_bounds.nw.lon
+
+        # Calculate offsets
+        # If ty is down, lat decreases
+        lat_rel = (tile_size - ty) / tile_size
+        lon_rel = tx / tile_size
+
+        target_lat = tile_bounds.sw.lat + (lat_span * lat_rel)
+        target_lon = tile_bounds.nw.lon + (lon_span * lon_rel)
+
+        return GPSPoint(lat=target_lat, lon=target_lon)
+
+    def align_to_satellite(
+        self,
+        uav_image: np.ndarray,
+        satellite_tile: np.ndarray,
+        tile_bounds: TileBounds,
+        uav_gsd_mpp: float = 0.0,
+    ) -> Optional[AlignmentResult]:
+        """Align UAV frame to satellite tile.
+
+        Args:
+            uav_gsd_mpp: If > 0, the UAV frame is GSD-normalised to satellite
+                         resolution before matching (SAT-03).
+        """
+        # SAT-03: optional GSD normalization
+        sat_gsd = tile_bounds.gsd
+        if uav_gsd_mpp > 0 and sat_gsd > 0:
+            uav_image = self.normalize_gsd(uav_image, uav_gsd_mpp, sat_gsd)
+
+        engine = self.model_manager.get_inference_engine("LiteSAM")
+        res = engine.infer({"img1": uav_image, "img2": satellite_tile})
+
+        if res["inlier_count"] < 15:
+            return None
+
+        h, w = uav_image.shape[:2] if hasattr(uav_image, "shape") else (480, 640)
+        gps = self.extract_gps_from_alignment(res["homography"], tile_bounds, (w // 2, h // 2))
+
+        # SAT-04: confidence = inlier_ratio (not raw engine confidence)
+        total = res.get("total_correspondences", max(res["inlier_count"], 1))
+        inlier_ratio = res["inlier_count"] / max(total, 1)
+
+        align = AlignmentResult(
+            matched=True,
+            homography=res["homography"],
+            gps_center=gps,
+            confidence=inlier_ratio,
+            inlier_count=res["inlier_count"],
+            total_correspondences=total,
+            reprojection_error=res.get("reprojection_error", 1.0),
+        )
+        return align if self.compute_match_confidence(align) > 0.5 else None
+
+    def compute_match_confidence(self, alignment: AlignmentResult) -> float:
+        # Complex heuristic combining inliers, reprojection error
+        score = alignment.confidence
+        # Penalty for high reproj error
+        if alignment.reprojection_error > 2.0:
+            score -= 0.2
+        return max(0.0, min(1.0, score))
+
+    def match_chunk_homography(self, chunk_images: List[np.ndarray], satellite_tile: np.ndarray) -> Optional[np.ndarray]:
+        # Aggregate logic is complex, for mock we just use the first image's match
+        if not chunk_images:
+            return None
+        return self.compute_homography(chunk_images[0], satellite_tile)
+
+    def align_chunk_to_satellite(self, chunk_images: List[np.ndarray], satellite_tile: np.ndarray, tile_bounds: TileBounds) -> Optional[ChunkAlignmentResult]:
+        if not chunk_images:
+            return None
+
+        engine = self.model_manager.get_inference_engine("LiteSAM")
+        res = engine.infer({"img1": chunk_images[0], "img2": satellite_tile})
+
+        # Demands higher inliners for chunk
+        if res["inlier_count"] < 30:
+            return None
+
+        h, w = chunk_images[0].shape[:2] if hasattr(chunk_images[0], "shape") else (480, 640)
+        gps = self.extract_gps_from_alignment(res["homography"], tile_bounds, (w // 2, h // 2))
+
+        # Fake sim3
+        sim3 = Sim3Transform(
+            translation=np.array([10., 0., 0.]),
+            rotation=np.eye(3),
+            scale=1.0
+        )
+
+        chunk_align = ChunkAlignmentResult(
+            matched=True,
+            chunk_id="chunk1",
+            chunk_center_gps=gps,
+            rotation_angle=0.0,
+            confidence=res["confidence"],
+            inlier_count=res["inlier_count"],
+            transform=sim3,
+            reprojection_error=1.0
+        )
+
+        return chunk_align

src/gps_denied/components/satellite_matcher/protocol.py

@@ -0,0 +1,103 @@
+"""Protocol surfaces for the satellite_matcher component (ARCH-05).
+
+Two Protocols live here per PATTERNS.md §3:
+
+  * ``SatelliteTileLoader`` — mirrors the concrete ``SatelliteDataManager``
+    public surface from ``core/satellite.py`` (no existing ABC).
+  * ``MetricRefiner`` — mirrors ``IMetricRefinement`` from ``core/metric.py``.
+
+Adapters move here in Plan 06 (satellite_matcher).
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Protocol, Tuple, runtime_checkable
+
+import numpy as np
+
+from gps_denied.schemas import GPSPoint
+from gps_denied.schemas.metric import AlignmentResult, ChunkAlignmentResult
+from gps_denied.schemas.satellite import TileBounds, TileCoords
+
+
+@runtime_checkable
+class SatelliteTileLoader(Protocol):
+    """Local satellite-tile reader / mosaic builder.
+
+    Mirrors the public surface of ``SatelliteDataManager`` (no ABC today).
+    """
+
+    def load_local_tile(self, tile_coords: TileCoords) -> np.ndarray | None: ...
+
+    def select_tiles_for_eskf_position(
+        self, gps: GPSPoint, sigma_h_m: float, zoom: int
+    ) -> list[TileCoords]: ...
+
+    def assemble_mosaic(
+        self,
+        tile_list: list[tuple[TileCoords, np.ndarray]],
+        target_size: int = 512,
+    ) -> tuple[np.ndarray, TileBounds] | None: ...
+
+    def fetch_tiles_for_position(
+        self, gps: GPSPoint, sigma_h_m: float, zoom: int
+    ) -> tuple[np.ndarray, TileBounds] | None: ...
+
+    def get_cached_tile(
+        self, flight_id: str, tile_coords: TileCoords
+    ) -> np.ndarray | None: ...
+
+    def cache_tile(
+        self, flight_id: str, tile_coords: TileCoords, tile_data: np.ndarray
+    ) -> bool: ...
+
+    def compute_tile_coords(self, lat: float, lon: float, zoom: int) -> TileCoords: ...
+
+    def compute_tile_bounds(self, tile_coords: TileCoords) -> TileBounds: ...
+
+    def clear_flight_cache(self, flight_id: str) -> bool: ...
+
+    def expand_search_grid(
+        self, center: TileCoords, current_size: int, new_size: int
+    ) -> list[TileCoords]: ...
+
+    def get_tile_grid(self, center: TileCoords, grid_size: int) -> list[TileCoords]: ...
+
+
+@runtime_checkable
+class MetricRefiner(Protocol):
+    """LiteSAM-style satellite alignment surface (mirrors IMetricRefinement)."""
+
+    def align_to_satellite(
+        self,
+        uav_image: np.ndarray,
+        satellite_tile: np.ndarray,
+        tile_bounds: TileBounds,
+    ) -> Optional[AlignmentResult]: ...
+
+    def compute_homography(
+        self, uav_image: np.ndarray, satellite_tile: np.ndarray
+    ) -> Optional[np.ndarray]: ...
+
+    def extract_gps_from_alignment(
+        self,
+        homography: np.ndarray,
+        tile_bounds: TileBounds,
+        image_center: Tuple[int, int],
+    ) -> GPSPoint: ...
+
+    def compute_match_confidence(self, alignment: AlignmentResult) -> float: ...
+
+    def align_chunk_to_satellite(
+        self,
+        chunk_images: List[np.ndarray],
+        satellite_tile: np.ndarray,
+        tile_bounds: TileBounds,
+    ) -> Optional[ChunkAlignmentResult]: ...
+
+    def match_chunk_homography(
+        self, chunk_images: List[np.ndarray], satellite_tile: np.ndarray
+    ) -> Optional[np.ndarray]: ...
+
+
+# Backwards-compat alias for the only ABC that previously existed.
+IMetricRefinement = MetricRefiner

src/gps_denied/components/vio/__init__.py

@@ -0,0 +1,37 @@
+"""VIO component (ARCH-01).
+
+Public surface for visual-inertial odometry adapters. Phase-1 split of
+the legacy ``core/vo.py`` monolith into per-backend modules:
+
+  - protocol.py         — VisualOdometry Protocol (alias ISequentialVisualOdometry)
+  - orbslam_backend.py  — pure-Python OpenCV: SequentialVisualOdometry + ORBVisualOdometry
+  - cuvslam_backend.py  — Jetson cuVSLAM SDK bridge: CuVSLAMVisualOdometry + CuVSLAMMonoDepthVisualOdometry
+  - factory.py          — create_vo_backend env-aware DI seed
+  - native/             — placeholder for future cuvslam SDK native glue
+
+The legacy ``gps_denied.core.vo`` import path is preserved as a thin
+re-export shim for one phase; tests still import from there.
+"""
+from gps_denied.components.vio.protocol import (
+    ISequentialVisualOdometry,
+    VisualOdometry,
+)
+from gps_denied.components.vio.orbslam_backend import (
+    ORBVisualOdometry,
+    SequentialVisualOdometry,
+)
+from gps_denied.components.vio.cuvslam_backend import (
+    CuVSLAMMonoDepthVisualOdometry,
+    CuVSLAMVisualOdometry,
+)
+from gps_denied.components.vio.factory import create_vo_backend
+
+__all__ = [
+    "VisualOdometry",
+    "ISequentialVisualOdometry",
+    "ORBVisualOdometry",
+    "SequentialVisualOdometry",
+    "CuVSLAMVisualOdometry",
+    "CuVSLAMMonoDepthVisualOdometry",
+    "create_vo_backend",
+]

src/gps_denied/components/vio/cuvslam_backend.py

@@ -0,0 +1,302 @@
+"""cuVSLAM SDK bridge backends (Jetson production path).
+
+Houses the two cuVSLAM-based VO backends:
+
+  - CuVSLAMVisualOdometry          — Inertial mode (stereo + IMU)
+  - CuVSLAMMonoDepthVisualOdometry — Mono-Depth mode (single camera + barometric depth hint)
+
+The cuVSLAM Python SDK is **only available on aarch64 Jetson**; on x86
+dev/CI machines the import fails and each class transparently falls back
+to ``ORBVisualOdometry`` from ``components.vio.orbslam_backend``. The
+fallback flag ``_CUVSLAM_AVAILABLE`` is exposed at module level so tests
+and the env-aware factory can branch on platform without re-probing the
+import.
+
+Decision recorded in
+``docs/superpowers/specs/2026-04-18-oss-stack-tech-audit-design.md``:
+Mono-Depth is the canonical path for the single-nadir-camera UAV
+hardware; Inertial mode is retained for sprint-1 reversibility.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import numpy as np
+
+from gps_denied.components.vio.orbslam_backend import ORBVisualOdometry
+from gps_denied.components.vio.protocol import ISequentialVisualOdometry
+from gps_denied.schemas import CameraParameters
+from gps_denied.schemas.vo import Features, Matches, Motion, RelativePose
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Optional cuVSLAM SDK import (aarch64 Jetson only — x86 dev/CI must still pass)
+# ---------------------------------------------------------------------------
+try:
+    import cuvslam  # type: ignore  # only available on Jetson
+    _CUVSLAM_AVAILABLE = True
+except ImportError:
+    cuvslam = None  # type: ignore[assignment]
+    _CUVSLAM_AVAILABLE = False
+
+
+# ---------------------------------------------------------------------------
+# CuVSLAMVisualOdometry — NVIDIA cuVSLAM Inertial mode (Jetson, VO-01)
+# ---------------------------------------------------------------------------
+
+class CuVSLAMVisualOdometry(ISequentialVisualOdometry):
+    """cuVSLAM wrapper for Jetson Orin (Inertial mode).
+
+    Provides metric relative poses in NED (scale_ambiguous=False).
+    Falls back to ORBVisualOdometry internally when the cuVSLAM SDK is absent
+    so the same class can be instantiated on dev/CI with scale_ambiguous reflecting
+    the actual backend capability.
+
+    Usage on Jetson:
+        vo = CuVSLAMVisualOdometry(camera_params, imu_params)
+        pose = vo.compute_relative_pose(prev, curr, cam)  # scale_ambiguous=False
+    """
+
+    def __init__(self, camera_params: Optional[CameraParameters] = None, imu_params: Optional[dict] = None):
+        self._camera_params = camera_params
+        self._imu_params = imu_params or {}
+        self._cuvslam = None
+        self._tracker = None
+        self._orb_fallback = ORBVisualOdometry()
+
+        try:
+            import cuvslam  # type: ignore  # only available on Jetson
+            self._cuvslam = cuvslam
+            self._init_tracker()
+            logger.info("CuVSLAMVisualOdometry: cuVSLAM SDK loaded (Jetson mode)")
+        except ImportError:
+            logger.info("CuVSLAMVisualOdometry: cuVSLAM not available — using ORB fallback (dev/CI mode)")
+
+    def _init_tracker(self):
+        """Initialise cuVSLAM tracker in Inertial mode."""
+        if self._cuvslam is None:
+            return
+        try:
+            cam = self._camera_params
+            rig_params = self._cuvslam.CameraRigParams()
+            if cam is not None:
+                f_px = cam.focal_length * (cam.resolution_width / cam.sensor_width)
+                cx = cam.principal_point[0] if cam.principal_point else cam.resolution_width / 2.0
+                cy = cam.principal_point[1] if cam.principal_point else cam.resolution_height / 2.0
+                rig_params.cameras[0].intrinsics = self._cuvslam.CameraIntrinsics(
+                    fx=f_px, fy=f_px, cx=cx, cy=cy,
+                    width=cam.resolution_width, height=cam.resolution_height,
+                )
+            tracker_params = self._cuvslam.TrackerParams()
+            tracker_params.use_imu = True
+            tracker_params.imu_noise_model = self._cuvslam.ImuNoiseModel(
+                accel_noise=self._imu_params.get("accel_noise", 0.01),
+                gyro_noise=self._imu_params.get("gyro_noise", 0.001),
+            )
+            self._tracker = self._cuvslam.Tracker(rig_params, tracker_params)
+            logger.info("cuVSLAM tracker initialised in Inertial mode")
+        except Exception as exc:
+            logger.error("cuVSLAM tracker init failed: %s", exc)
+            self._cuvslam = None
+
+    @property
+    def _has_cuvslam(self) -> bool:
+        return self._cuvslam is not None and self._tracker is not None
+
+    # ------------------------------------------------------------------
+    # ISequentialVisualOdometry interface — delegate to cuVSLAM or ORB
+    # ------------------------------------------------------------------
+
+    def extract_features(self, image: np.ndarray) -> Features:
+        return self._orb_fallback.extract_features(image)
+
+    def match_features(self, features1: Features, features2: Features) -> Matches:
+        return self._orb_fallback.match_features(features1, features2)
+
+    def estimate_motion(self, matches: Matches, camera_params: CameraParameters) -> Optional[Motion]:
+        return self._orb_fallback.estimate_motion(matches, camera_params)
+
+    def compute_relative_pose(
+        self, prev_image: np.ndarray, curr_image: np.ndarray, camera_params: CameraParameters
+    ) -> Optional[RelativePose]:
+        if self._has_cuvslam:
+            return self._compute_via_cuvslam(curr_image, camera_params)
+        # Dev/CI fallback — ORB with scale_ambiguous still marked False to signal
+        # this class is *intended* as the metric backend (ESKF provides scale externally)
+        pose = self._orb_fallback.compute_relative_pose(prev_image, curr_image, camera_params)
+        if pose is None:
+            return None
+        return RelativePose(
+            translation=pose.translation,
+            rotation=pose.rotation,
+            confidence=pose.confidence,
+            inlier_count=pose.inlier_count,
+            total_matches=pose.total_matches,
+            tracking_good=pose.tracking_good,
+            scale_ambiguous=False,  # VO-04: cuVSLAM Inertial = metric; ESKF provides scale ref on dev
+        )
+
+    def _compute_via_cuvslam(self, image: np.ndarray, camera_params: CameraParameters) -> Optional[RelativePose]:
+        """Run cuVSLAM tracking step and convert result to RelativePose."""
+        try:
+            result = self._tracker.track(image)
+            if result is None or not result.tracking_ok:
+                return None
+            R = np.array(result.rotation).reshape(3, 3)
+            t = np.array(result.translation)
+            return RelativePose(
+                translation=t,
+                rotation=R,
+                confidence=float(getattr(result, "confidence", 1.0)),
+                inlier_count=int(getattr(result, "inlier_count", 100)),
+                total_matches=int(getattr(result, "total_matches", 100)),
+                tracking_good=True,
+                scale_ambiguous=False,  # VO-04: cuVSLAM Inertial mode = metric NED
+            )
+        except Exception as exc:
+            logger.error("cuVSLAM tracking step failed: %s", exc)
+            return None
+
+
+# ---------------------------------------------------------------------------
+# CuVSLAMMonoDepthVisualOdometry — cuVSLAM Mono-Depth mode (sprint 1 production)
+# ---------------------------------------------------------------------------
+# TODO(sprint 2): collapse duplicated SDK-load / _init_tracker scaffolding with
+# CuVSLAMVisualOdometry once Inertial mode is removed. Kept separate for sprint 1
+# so the Inertial → Mono-Depth migration is reversible.
+
+# Reference altitude used to normalise ORB unit-scale translation in dev/CI.
+# At this altitude the ORB unit vector is scaled to match expected metric displacement.
+_MONO_DEPTH_REFERENCE_ALTITUDE_M = 600.0
+
+
+class CuVSLAMMonoDepthVisualOdometry(ISequentialVisualOdometry):
+    """cuVSLAM Mono-Depth wrapper — barometer altitude as synthetic depth.
+
+    Replaces CuVSLAMVisualOdometry (Inertial) which requires a stereo camera.
+    cuVSLAM Mono-Depth accepts a depth hint (barometric altitude) to recover
+    metric scale from a single nadir camera.
+
+    On dev/CI (no cuVSLAM SDK): falls back to ORBVisualOdometry and scales
+    translation by depth_hint_m / _MONO_DEPTH_REFERENCE_ALTITUDE_M so that
+    the dev/CI metric magnitude is consistent with the Jetson production output.
+
+    Note — solution.md records OdometryMode=INERTIAL which requires stereo.
+    This class uses OdometryMode=MONO_DEPTH, the correct mode for our hardware.
+    Decision recorded in docs/superpowers/specs/2026-04-18-oss-stack-tech-audit-design.md.
+    """
+
+    def __init__(
+        self,
+        depth_hint_m: float = _MONO_DEPTH_REFERENCE_ALTITUDE_M,
+        camera_params: Optional[CameraParameters] = None,
+        imu_params: Optional[dict] = None,
+    ):
+        self._depth_hint_m = depth_hint_m
+        self._camera_params = camera_params
+        self._imu_params = imu_params or {}
+        self._cuvslam = None
+        self._tracker = None
+        self._orb_fallback = ORBVisualOdometry()
+
+        try:
+            import cuvslam  # type: ignore
+            self._cuvslam = cuvslam
+            self._init_tracker()
+            logger.info("CuVSLAMMonoDepthVisualOdometry: cuVSLAM SDK loaded (Jetson Mono-Depth mode)")
+        except ImportError:
+            logger.info("CuVSLAMMonoDepthVisualOdometry: cuVSLAM not available — using scaled ORB fallback")
+
+    def update_depth_hint(self, depth_hint_m: float) -> None:
+        """Update barometric altitude used for scale recovery. Call each frame."""
+        self._depth_hint_m = max(depth_hint_m, 1.0)
+
+    def _init_tracker(self) -> None:
+        if self._cuvslam is None:
+            return
+        try:
+            cam = self._camera_params
+            rig_params = self._cuvslam.CameraRigParams()
+            if cam is not None:
+                f_px = cam.focal_length * (cam.resolution_width / cam.sensor_width)
+                cx = cam.principal_point[0] if cam.principal_point else cam.resolution_width / 2.0
+                cy = cam.principal_point[1] if cam.principal_point else cam.resolution_height / 2.0
+                rig_params.cameras[0].intrinsics = self._cuvslam.CameraIntrinsics(
+                    fx=f_px, fy=f_px, cx=cx, cy=cy,
+                    width=cam.resolution_width, height=cam.resolution_height,
+                )
+            tracker_params = self._cuvslam.TrackerParams()
+            tracker_params.use_imu = False
+            tracker_params.odometry_mode = self._cuvslam.OdometryMode.MONO_DEPTH
+            self._tracker = self._cuvslam.Tracker(rig_params, tracker_params)
+            logger.info("cuVSLAM tracker initialised in Mono-Depth mode")
+        except Exception:
+            logger.exception(
+                "cuVSLAM Mono-Depth tracker init FAILED — falling back to ORB. "
+                "Production Jetson path is DISABLED until this is fixed."
+            )
+            self._cuvslam = None
+
+    @property
+    def _has_cuvslam(self) -> bool:
+        return self._cuvslam is not None and self._tracker is not None
+
+    def extract_features(self, image: np.ndarray) -> Features:
+        return self._orb_fallback.extract_features(image)
+
+    def match_features(self, features1: Features, features2: Features) -> Matches:
+        return self._orb_fallback.match_features(features1, features2)
+
+    def estimate_motion(self, matches: Matches, camera_params: CameraParameters) -> Optional[Motion]:
+        return self._orb_fallback.estimate_motion(matches, camera_params)
+
+    def compute_relative_pose(
+        self,
+        prev_image: np.ndarray,
+        curr_image: np.ndarray,
+        camera_params: CameraParameters,
+    ) -> Optional[RelativePose]:
+        if self._has_cuvslam:
+            return self._compute_via_cuvslam(curr_image)
+        return self._compute_via_orb_scaled(prev_image, curr_image, camera_params)
+
+    def _compute_via_cuvslam(self, image: np.ndarray) -> Optional[RelativePose]:
+        try:
+            result = self._tracker.track(image, depth_hint=self._depth_hint_m)
+            if result is None or not result.tracking_ok:
+                return None
+            return RelativePose(
+                translation=np.array(result.translation),
+                rotation=np.array(result.rotation).reshape(3, 3),
+                confidence=float(getattr(result, "confidence", 1.0)),
+                inlier_count=int(getattr(result, "inlier_count", 100)),
+                total_matches=int(getattr(result, "total_matches", 100)),
+                tracking_good=True,
+                scale_ambiguous=False,
+            )
+        except Exception:
+            logger.exception("cuVSLAM Mono-Depth tracking step failed — frame dropped")
+            return None
+
+    def _compute_via_orb_scaled(
+        self,
+        prev_image: np.ndarray,
+        curr_image: np.ndarray,
+        camera_params: CameraParameters,
+    ) -> Optional[RelativePose]:
+        """Dev/CI fallback: ORB translation scaled by depth_hint_m."""
+        pose = self._orb_fallback.compute_relative_pose(prev_image, curr_image, camera_params)
+        if pose is None:
+            return None
+        scale = self._depth_hint_m / _MONO_DEPTH_REFERENCE_ALTITUDE_M
+        return RelativePose(
+            translation=pose.translation * scale,
+            rotation=pose.rotation,
+            confidence=pose.confidence,
+            inlier_count=pose.inlier_count,
+            total_matches=pose.total_matches,
+            tracking_good=pose.tracking_good,
+            scale_ambiguous=False,
+        )

src/gps_denied/components/vio/factory.py

@@ -0,0 +1,67 @@
+"""VIO backend factory — env-aware DI seed (ARCH-01 / ARCH-03).
+
+Preserves ``create_vo_backend`` verbatim from the legacy ``core/vo.py``
+location. PATTERNS.md §4.1 explicitly designates this factory as the
+seed of the env-aware composition root: ``pipeline/composition.py``
+(Plan 08) will pass env-specific kwargs (``prefer_cuvslam``,
+``prefer_mono_depth``, ``model_manager``) into this function from
+``RuntimeConfig``.
+
+Signature contract for Plan 08 wiring:
+
+  - ``env="jetson"``           → prefer_cuvslam=True,  prefer_mono_depth=True
+  - ``env="x86_dev" | "ci"``   → prefer_cuvslam=False, model_manager=mock
+  - ``env="sitl"``             → prefer_cuvslam=False
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from gps_denied.components.vio.cuvslam_backend import (
+    CuVSLAMMonoDepthVisualOdometry,
+    CuVSLAMVisualOdometry,
+)
+from gps_denied.components.vio.orbslam_backend import (
+    ORBVisualOdometry,
+    SequentialVisualOdometry,
+)
+from gps_denied.components.vio.protocol import VisualOdometry
+from gps_denied.core.models import IModelManager
+from gps_denied.schemas import CameraParameters
+
+
+def create_vo_backend(
+    model_manager: Optional[IModelManager] = None,
+    prefer_cuvslam: bool = True,
+    prefer_mono_depth: bool = False,
+    camera_params: Optional[CameraParameters] = None,
+    imu_params: Optional[dict] = None,
+    depth_hint_m: float = 600.0,
+) -> VisualOdometry:
+    """Return the best available VO backend for the current platform.
+
+    Priority when prefer_mono_depth=True:
+      1. CuVSLAMMonoDepthVisualOdometry (sprint 1 production path)
+      2. ORBVisualOdometry (dev/CI fallback inside Mono-Depth wrapper)
+
+    Priority when prefer_mono_depth=False (legacy):
+      1. CuVSLAMVisualOdometry (Jetson — cuVSLAM SDK present)
+      2. SequentialVisualOdometry (TRT/Mock SuperPoint+LightGlue)
+      3. ORBVisualOdometry (pure OpenCV fallback)
+    """
+    if prefer_mono_depth:
+        return CuVSLAMMonoDepthVisualOdometry(
+            depth_hint_m=depth_hint_m,
+            camera_params=camera_params,
+            imu_params=imu_params,
+        )
+
+    if prefer_cuvslam:
+        vo = CuVSLAMVisualOdometry(camera_params=camera_params, imu_params=imu_params)
+        if vo._has_cuvslam:
+            return vo
+
+    if model_manager is not None:
+        return SequentialVisualOdometry(model_manager)
+
+    return ORBVisualOdometry()

src/gps_denied/components/vio/native/__init__.py

@@ -0,0 +1,6 @@
+"""Native bridge code for cuvslam SDK (placeholder).
+
+Phase 1: empty. Future stages may add ctypes/Cython wrappers around the
+cuvslam wheel if version-skew or platform-specific glue is needed. For
+now the SDK is imported directly in cuvslam_backend.py.
+"""

src/gps_denied/components/vio/orbslam_backend.py

@@ -0,0 +1,260 @@
+"""Pure-Python OpenCV VO backends (ARCH-01 / ARCH-05).
+
+Houses the two OpenCV-only VO implementations that have no native SDK
+dependency:
+
+  - SequentialVisualOdometry — SuperPoint + LightGlue (TRT on Jetson / Mock on dev)
+  - ORBVisualOdometry        — OpenCV ORB + BFMatcher (dev/CI stub, VO-02)
+
+Both implement the ``VisualOdometry`` Protocol (alias
+``ISequentialVisualOdometry``) defined in ``components.vio.protocol``. This
+module deliberately does NOT import ``cuvslam`` — the cuVSLAM-bridge
+backends live in ``components.vio.cuvslam_backend`` and keep that
+optional-import block isolated.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import cv2
+import numpy as np
+
+from gps_denied.components.vio.protocol import ISequentialVisualOdometry
+from gps_denied.core.models import IModelManager
+from gps_denied.schemas import CameraParameters
+from gps_denied.schemas.vo import Features, Matches, Motion, RelativePose
+
+logger = logging.getLogger(__name__)
+
+
+class SequentialVisualOdometry(ISequentialVisualOdometry):
+    """Frame-to-frame visual odometry using SuperPoint + LightGlue."""
+
+    def __init__(self, model_manager: IModelManager):
+        self.model_manager = model_manager
+
+    def extract_features(self, image: np.ndarray) -> Features:
+        """Extracts keypoints and descriptors using SuperPoint."""
+        engine = self.model_manager.get_inference_engine("SuperPoint")
+        result = engine.infer(image)
+
+        return Features(
+            keypoints=result["keypoints"],
+            descriptors=result["descriptors"],
+            scores=result["scores"]
+        )
+
+    def match_features(self, features1: Features, features2: Features) -> Matches:
+        """Matches features using LightGlue."""
+        engine = self.model_manager.get_inference_engine("LightGlue")
+        result = engine.infer({
+            "features1": features1,
+            "features2": features2
+        })
+
+        return Matches(
+            matches=result["matches"],
+            scores=result["scores"],
+            keypoints1=result["keypoints1"],
+            keypoints2=result["keypoints2"]
+        )
+
+    def estimate_motion(self, matches: Matches, camera_params: CameraParameters) -> Motion | None:
+        """Estimates camera motion using Essential Matrix (RANSAC)."""
+        inlier_threshold = 20
+        if len(matches.matches) < 8:
+            return None
+
+        pts1 = np.ascontiguousarray(matches.keypoints1)
+        pts2 = np.ascontiguousarray(matches.keypoints2)
+
+        # Build camera matrix
+        f_px = camera_params.focal_length * (camera_params.resolution_width / camera_params.sensor_width)
+        if camera_params.principal_point:
+            cx, cy = camera_params.principal_point
+        else:
+            cx = camera_params.resolution_width / 2.0
+            cy = camera_params.resolution_height / 2.0
+
+        K = np.array([
+            [f_px, 0, cx],
+            [0, f_px, cy],
+            [0, 0,  1]
+        ], dtype=np.float64)
+
+        try:
+            E, inliers = cv2.findEssentialMat(
+                pts1, pts2, cameraMatrix=K, method=cv2.RANSAC, prob=0.999, threshold=1.0
+            )
+        except Exception as e:
+            logger.error(f"Error finding essential matrix: {e}")
+            return None
+
+        if E is None or E.shape != (3, 3):
+            return None
+
+        inliers_mask = inliers.flatten().astype(bool)
+        inlier_count = np.sum(inliers_mask)
+
+        if inlier_count < inlier_threshold:
+            logger.warning(f"Insufficient inliers: {inlier_count} < {inlier_threshold}")
+            return None
+
+        # Recover pose
+        try:
+            _, R, t, mask = cv2.recoverPose(E, pts1, pts2, cameraMatrix=K, mask=inliers)
+        except Exception as e:
+            logger.error(f"Error recovering pose: {e}")
+            return None
+
+        return Motion(
+            translation=t.flatten(),
+            rotation=R,
+            inliers=inliers_mask,
+            inlier_count=inlier_count
+        )
+
+    def compute_relative_pose(
+        self, prev_image: np.ndarray, curr_image: np.ndarray, camera_params: CameraParameters
+    ) -> RelativePose | None:
+        """Computes relative pose between two frames."""
+        f1 = self.extract_features(prev_image)
+        f2 = self.extract_features(curr_image)
+
+        matches = self.match_features(f1, f2)
+
+        motion = self.estimate_motion(matches, camera_params)
+
+        if motion is None:
+            return None
+
+        tracking_good = motion.inlier_count > 50
+
+        return RelativePose(
+            translation=motion.translation,
+            rotation=motion.rotation,
+            confidence=float(motion.inlier_count / max(1, len(matches.matches))),
+            inlier_count=motion.inlier_count,
+            total_matches=len(matches.matches),
+            tracking_good=tracking_good,
+            scale_ambiguous=True,
+        )
+
+
+# ---------------------------------------------------------------------------
+# ORBVisualOdometry — OpenCV ORB stub for dev/CI (VO-02)
+# ---------------------------------------------------------------------------
+
+class ORBVisualOdometry(ISequentialVisualOdometry):
+    """OpenCV ORB-based VO stub for x86 dev/CI environments.
+
+    Satisfies the same ISequentialVisualOdometry interface as the cuVSLAM wrapper.
+    Translation is unit-scale (scale_ambiguous=True) — metric scale requires ESKF.
+    """
+
+    _MIN_INLIERS = 20
+    _N_FEATURES = 2000
+
+    def __init__(self):
+        self._orb = cv2.ORB_create(nfeatures=self._N_FEATURES)
+        self._matcher = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=False)
+
+    # ------------------------------------------------------------------
+    # ISequentialVisualOdometry interface
+    # ------------------------------------------------------------------
+
+    def extract_features(self, image: np.ndarray) -> Features:
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image
+        kps, descs = self._orb.detectAndCompute(gray, None)
+        if descs is None or len(kps) == 0:
+            return Features(
+                keypoints=np.zeros((0, 2), dtype=np.float32),
+                descriptors=np.zeros((0, 32), dtype=np.uint8),
+                scores=np.zeros(0, dtype=np.float32),
+            )
+        pts = np.array([[k.pt[0], k.pt[1]] for k in kps], dtype=np.float32)
+        scores = np.array([k.response for k in kps], dtype=np.float32)
+        return Features(keypoints=pts, descriptors=descs.astype(np.float32), scores=scores)
+
+    def match_features(self, features1: Features, features2: Features) -> Matches:
+        if len(features1.keypoints) == 0 or len(features2.keypoints) == 0:
+            return Matches(
+                matches=np.zeros((0, 2), dtype=np.int32),
+                scores=np.zeros(0, dtype=np.float32),
+                keypoints1=np.zeros((0, 2), dtype=np.float32),
+                keypoints2=np.zeros((0, 2), dtype=np.float32),
+            )
+        d1 = features1.descriptors.astype(np.uint8)
+        d2 = features2.descriptors.astype(np.uint8)
+        raw = self._matcher.knnMatch(d1, d2, k=2)
+        # Lowe ratio test
+        good = []
+        for pair in raw:
+            if len(pair) == 2 and pair[0].distance < 0.75 * pair[1].distance:
+                good.append(pair[0])
+        if not good:
+            return Matches(
+                matches=np.zeros((0, 2), dtype=np.int32),
+                scores=np.zeros(0, dtype=np.float32),
+                keypoints1=np.zeros((0, 2), dtype=np.float32),
+                keypoints2=np.zeros((0, 2), dtype=np.float32),
+            )
+        idx = np.array([[m.queryIdx, m.trainIdx] for m in good], dtype=np.int32)
+        scores = np.array([1.0 / (1.0 + m.distance) for m in good], dtype=np.float32)
+        kp1 = features1.keypoints[idx[:, 0]]
+        kp2 = features2.keypoints[idx[:, 1]]
+        return Matches(matches=idx, scores=scores, keypoints1=kp1, keypoints2=kp2)
+
+    def estimate_motion(self, matches: Matches, camera_params: CameraParameters) -> Optional[Motion]:
+        if len(matches.matches) < 8:
+            return None
+        pts1 = np.ascontiguousarray(matches.keypoints1, dtype=np.float64)
+        pts2 = np.ascontiguousarray(matches.keypoints2, dtype=np.float64)
+        f_px = camera_params.focal_length * (
+            camera_params.resolution_width / camera_params.sensor_width
+        )
+        cx = (camera_params.principal_point[0]
+              if camera_params.principal_point
+              else camera_params.resolution_width / 2.0)
+        cy = (camera_params.principal_point[1]
+              if camera_params.principal_point
+              else camera_params.resolution_height / 2.0)
+        K = np.array([[f_px, 0, cx], [0, f_px, cy], [0, 0, 1]], dtype=np.float64)
+        try:
+            E, inliers = cv2.findEssentialMat(pts1, pts2, cameraMatrix=K, method=cv2.RANSAC, prob=0.999, threshold=1.0)
+        except Exception as exc:
+            logger.warning("ORB findEssentialMat failed: %s", exc)
+            return None
+        if E is None or E.shape != (3, 3) or inliers is None:
+            return None
+        inlier_mask = inliers.flatten().astype(bool)
+        inlier_count = int(np.sum(inlier_mask))
+        if inlier_count < self._MIN_INLIERS:
+            return None
+        try:
+            _, R, t, mask = cv2.recoverPose(E, pts1, pts2, cameraMatrix=K, mask=inliers)
+        except Exception as exc:
+            logger.warning("ORB recoverPose failed: %s", exc)
+            return None
+        return Motion(translation=t.flatten(), rotation=R, inliers=inlier_mask, inlier_count=inlier_count)
+
+    def compute_relative_pose(
+        self, prev_image: np.ndarray, curr_image: np.ndarray, camera_params: CameraParameters
+    ) -> Optional[RelativePose]:
+        f1 = self.extract_features(prev_image)
+        f2 = self.extract_features(curr_image)
+        matches = self.match_features(f1, f2)
+        motion = self.estimate_motion(matches, camera_params)
+        if motion is None:
+            return None
+        tracking_good = motion.inlier_count >= self._MIN_INLIERS
+        return RelativePose(
+            translation=motion.translation,
+            rotation=motion.rotation,
+            confidence=float(motion.inlier_count / max(1, len(matches.matches))),
+            inlier_count=motion.inlier_count,
+            total_matches=len(matches.matches),
+            tracking_good=tracking_good,
+            scale_ambiguous=True,  # monocular ORB cannot recover metric scale
+        )

src/gps_denied/components/vio/protocol.py

@@ -0,0 +1,35 @@
+"""Protocol surface for the VIO component (ARCH-05).
+
+Phase 1: defines the Protocol that concrete adapters in this directory
+implement. Method signatures mirror ``ISequentialVisualOdometry`` from
+``core/vo.py``. Adapters are NOT moved here yet — see Plan 04 (VIO).
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+from gps_denied.schemas import CameraParameters
+from gps_denied.schemas.vo import Features, Matches, Motion, RelativePose
+
+
+@runtime_checkable
+class VisualOdometry(Protocol):
+    """Sequential visual odometry surface (mirrors ISequentialVisualOdometry)."""
+
+    def compute_relative_pose(
+        self, prev_image: np.ndarray, curr_image: np.ndarray, camera_params: CameraParameters
+    ) -> RelativePose | None: ...
+
+    def extract_features(self, image: np.ndarray) -> Features: ...
+
+    def match_features(self, features1: Features, features2: Features) -> Matches: ...
+
+    def estimate_motion(
+        self, matches: Matches, camera_params: CameraParameters
+    ) -> Motion | None: ...
+
+
+# Backwards-compat alias — Phase 2 will deprecate the I-prefix.
+ISequentialVisualOdometry = VisualOdometry

src/gps_denied/config.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Literal
 
 from pydantic import Field
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings import BaseSettings, SettingsConfigDict, YamlConfigSettingsSource
 
 
 class DatabaseConfig(BaseSettings):
@@ -162,6 +163,8 @@ class AppSettings(BaseSettings):
         extra="ignore",
     )
 
+    env: Literal["jetson", "x86_dev", "ci", "sitl"] = "x86_dev"
+
     db: DatabaseConfig = Field(default_factory=DatabaseConfig)
     api: APIConfig = Field(default_factory=APIConfig)
     tiles: TileProviderConfig = Field(default_factory=TileProviderConfig)
@@ -174,6 +177,36 @@ class AppSettings(BaseSettings):
     satellite: SatelliteConfig = Field(default_factory=SatelliteConfig)
     eskf: ESKFSettings = Field(default_factory=ESKFSettings)
 
+    @classmethod
+    def settings_customise_sources(cls, settings_cls, **kwargs):
+        """Load YAML overlay from config/{env}.yaml when present."""
+        import os
+        import yaml
+
+        init_kwargs = kwargs.get("init_settings")
+        env_settings = kwargs.get("env_settings")
+        dotenv = kwargs.get("dotenv_settings")
+        file_secret = kwargs.get("file_secret_settings")
+
+        # Determine which env we're in (check ENV env-var before loading YAML)
+        current_env = os.environ.get("ENV", "x86_dev")
+        yaml_path = Path(f"config/{current_env}.yaml")
+
+        yaml_source = None
+        if yaml_path.exists():
+            try:
+                yaml_source = YamlConfigSettingsSource(settings_cls, yaml_file=yaml_path)
+            except Exception:
+                yaml_source = None
+
+        sources = [s for s in [init_kwargs, env_settings, dotenv, file_secret] if s is not None]
+        if yaml_source is not None:
+            sources.append(yaml_source)
+        return tuple(sources)
+
+
+# Alias for external consumers that expect RuntimeConfig
+RuntimeConfig = AppSettings
 
 _settings: AppSettings | None = None
 

src/gps_denied/core/benchmark.py

@@ -1,371 +1,8 @@
-"""Accuracy Benchmark (Phase 7).
-
-Provides:
-  - SyntheticTrajectory  — generates a realistic fixed-wing UAV flight path
-                           with ground-truth GPS + noisy sensor data.
-  - AccuracyBenchmark    — replays a trajectory through the ESKF pipeline
-                           and computes position-error statistics.
-
-Acceptance criteria (from solution.md):
-  AC-PERF-1: 80 % of frames within 50 m of ground truth.
-  AC-PERF-2: 60 % of frames within 20 m of ground truth.
-  AC-PERF-3: End-to-end per-frame latency < 400 ms.
-  AC-PERF-4: VO drift over 1 km straight segment (no sat correction) < 100 m.
-"""
-
-from __future__ import annotations
-
-import math
-import time
-from dataclasses import dataclass, field
-from typing import Callable, Optional
-
-import numpy as np
-
-from gps_denied.core.coordinates import CoordinateTransformer
-from gps_denied.core.eskf import ESKF
-from gps_denied.schemas import GPSPoint
-from gps_denied.schemas.eskf import ESKFConfig, IMUMeasurement
-
-# ---------------------------------------------------------------------------
-# Synthetic trajectory
-# ---------------------------------------------------------------------------
-
-@dataclass
-class TrajectoryFrame:
-    """One simulated camera frame with ground-truth and noisy sensor data."""
-    frame_id: int
-    timestamp: float
-    true_position_enu: np.ndarray     # (3,) East, North, Up in metres
-    true_gps: GPSPoint                # WGS84 from true ENU
-    imu_measurements: list[IMUMeasurement]  # High-rate IMU between frames
-    vo_translation: Optional[np.ndarray]    # Noisy relative displacement (3,)
-    vo_tracking_good: bool = True
-
-
-@dataclass
-class SyntheticTrajectoryConfig:
-    """Parameters for trajectory generation."""
-    # Origin (mission start)
-    origin: GPSPoint = field(default_factory=lambda: GPSPoint(lat=49.0, lon=32.0))
-    altitude_m: float = 600.0           # Constant AGL altitude (m)
-    # UAV speed and heading
-    speed_mps: float = 20.0             # ~70 km/h (typical fixed-wing)
-    heading_deg: float = 45.0           # Initial heading (degrees CW from North)
-    camera_fps: float = 0.7             # ADTI 20L V1 camera rate (Hz)
-    imu_hz: float = 200.0               # IMU sample rate
-    num_frames: int = 50                # Number of camera frames to simulate
-    # Noise parameters
-    vo_noise_m: float = 0.5             # VO translation noise (sigma, metres)
-    imu_accel_noise: float = 0.01       # Accelerometer noise sigma (m/s²)
-    imu_gyro_noise: float = 0.001       # Gyroscope noise sigma (rad/s)
-    # Failure injection
-    vo_failure_frames: list[int] = field(default_factory=list)
-    # Waypoints for heading changes (ENU East, North metres from origin)
-    waypoints_enu: list[tuple[float, float]] = field(default_factory=list)
-
-
-class SyntheticTrajectory:
-    """Generate a synthetic fixed-wing UAV flight with ground truth + noisy sensors."""
-
-    def __init__(self, config: SyntheticTrajectoryConfig | None = None):
-        self.config = config or SyntheticTrajectoryConfig()
-        self._coord = CoordinateTransformer()
-        self._flight_id = "__synthetic__"
-        self._coord.set_enu_origin(self._flight_id, self.config.origin)
-
-    def generate(self) -> list[TrajectoryFrame]:
-        """Generate all trajectory frames."""
-        cfg = self.config
-        dt_camera = 1.0 / cfg.camera_fps
-        dt_imu = 1.0 / cfg.imu_hz
-        imu_steps = int(dt_camera * cfg.imu_hz)
-
-        frames: list[TrajectoryFrame] = []
-        pos = np.array([0.0, 0.0, cfg.altitude_m])
-        vel = self._heading_to_enu_vel(cfg.heading_deg, cfg.speed_mps)
-        prev_pos = pos.copy()
-        t = time.time()
-
-        waypoints = list(cfg.waypoints_enu)  # copy
-
-        for fid in range(cfg.num_frames):
-            # --- Waypoint steering ---
-            if waypoints:
-                wp_e, wp_n = waypoints[0]
-                to_wp = np.array([wp_e - pos[0], wp_n - pos[1], 0.0])
-                dist_wp = np.linalg.norm(to_wp[:2])
-                if dist_wp < cfg.speed_mps * dt_camera:
-                    waypoints.pop(0)
-                else:
-                    heading_rad = math.atan2(to_wp[0], to_wp[1])  # ENU: E=X, N=Y
-                    vel = np.array([
-                        cfg.speed_mps * math.sin(heading_rad),
-                        cfg.speed_mps * math.cos(heading_rad),
-                        0.0,
-                    ])
-
-            # --- Simulate IMU between frames ---
-            imu_list: list[IMUMeasurement] = []
-            for step in range(imu_steps):
-                ts = t + step * dt_imu
-                # Body-frame acceleration (mostly gravity correction, small forward accel)
-                accel_true = np.array([0.0, 0.0, 9.81])  # gravity compensation
-                gyro_true = np.zeros(3)
-                imu = IMUMeasurement(
-                    accel=accel_true + np.random.randn(3) * cfg.imu_accel_noise,
-                    gyro=gyro_true + np.random.randn(3) * cfg.imu_gyro_noise,
-                    timestamp=ts,
-                )
-                imu_list.append(imu)
-
-            # --- Propagate position ---
-            prev_pos = pos.copy()
-            pos = pos + vel * dt_camera
-            t += dt_camera
-
-            # --- True GPS from ENU position ---
-            true_gps = self._coord.enu_to_gps(
-                self._flight_id, (float(pos[0]), float(pos[1]), float(pos[2]))
-            )
-
-            # --- VO measurement (relative displacement + noise) ---
-            true_displacement = pos - prev_pos
-            vo_tracking_good = fid not in cfg.vo_failure_frames
-            if vo_tracking_good:
-                noisy_displacement = true_displacement + np.random.randn(3) * cfg.vo_noise_m
-                noisy_displacement[2] = 0.0  # monocular VO is scale-ambiguous in Z
-            else:
-                noisy_displacement = None
-
-            frames.append(TrajectoryFrame(
-                frame_id=fid,
-                timestamp=t,
-                true_position_enu=pos.copy(),
-                true_gps=true_gps,
-                imu_measurements=imu_list,
-                vo_translation=noisy_displacement,
-                vo_tracking_good=vo_tracking_good,
-            ))
-
-        return frames
-
-    @staticmethod
-    def _heading_to_enu_vel(heading_deg: float, speed_mps: float) -> np.ndarray:
-        """Convert heading (degrees CW from North) to ENU velocity vector."""
-        rad = math.radians(heading_deg)
-        return np.array([
-            speed_mps * math.sin(rad),   # East
-            speed_mps * math.cos(rad),   # North
-            0.0,                         # Up
-        ])
-
-
-# ---------------------------------------------------------------------------
-# Accuracy Benchmark
-# ---------------------------------------------------------------------------
-
-@dataclass
-class BenchmarkResult:
-    """Position error statistics over a trajectory replay."""
-    errors_m: list[float]               # Per-frame horizontal error in metres
-    latencies_ms: list[float]           # Per-frame process time in ms
-    frames_total: int
-    frames_with_good_estimate: int
-
-    @property
-    def p80_error_m(self) -> float:
-        """80th percentile position error (metres)."""
-        return float(np.percentile(self.errors_m, 80)) if self.errors_m else float("inf")
-
-    @property
-    def p60_error_m(self) -> float:
-        """60th percentile position error (metres)."""
-        return float(np.percentile(self.errors_m, 60)) if self.errors_m else float("inf")
-
-    @property
-    def median_error_m(self) -> float:
-        """Median position error (metres)."""
-        return float(np.median(self.errors_m)) if self.errors_m else float("inf")
-
-    @property
-    def max_error_m(self) -> float:
-        return float(max(self.errors_m)) if self.errors_m else float("inf")
-
-    @property
-    def p95_latency_ms(self) -> float:
-        """95th percentile frame latency (ms)."""
-        return float(np.percentile(self.latencies_ms, 95)) if self.latencies_ms else float("inf")
-
-    @property
-    def pct_within_50m(self) -> float:
-        """Fraction of frames within 50 m error."""
-        if not self.errors_m:
-            return 0.0
-        return sum(e <= 50.0 for e in self.errors_m) / len(self.errors_m)
-
-    @property
-    def pct_within_20m(self) -> float:
-        """Fraction of frames within 20 m error."""
-        if not self.errors_m:
-            return 0.0
-        return sum(e <= 20.0 for e in self.errors_m) / len(self.errors_m)
-
-    def passes_acceptance_criteria(self) -> tuple[bool, dict[str, bool]]:
-        """Check all solution.md acceptance criteria.
-
-        Returns (overall_pass, per_criterion_dict).
-        """
-        checks = {
-            "AC-PERF-1: 80% within 50m": self.pct_within_50m >= 0.80,
-            "AC-PERF-2: 60% within 20m": self.pct_within_20m >= 0.60,
-            "AC-PERF-3: p95 latency < 400ms": self.p95_latency_ms < 400.0,
-        }
-        overall = all(checks.values())
-        return overall, checks
-
-    def summary(self) -> str:
-        overall, checks = self.passes_acceptance_criteria()
-        lines = [
-            f"Frames: {self.frames_total}  |  with estimate: {self.frames_with_good_estimate}",
-            f"Error  — median: {self.median_error_m:.1f}m  p80: {self.p80_error_m:.1f}m  "
-            f"p60: {self.p60_error_m:.1f}m  max: {self.max_error_m:.1f}m",
-            f"Within 50m: {self.pct_within_50m*100:.1f}%  |  within 20m: {self.pct_within_20m*100:.1f}%",
-            f"Latency p95: {self.p95_latency_ms:.1f}ms",
-            "",
-            "Acceptance criteria:",
-        ]
-        for criterion, passed in checks.items():
-            lines.append(f"  {'PASS' if passed else 'FAIL'}  {criterion}")
-        lines.append(f"\nOverall: {'PASS' if overall else 'FAIL'}")
-        return "\n".join(lines)
-
-
-class AccuracyBenchmark:
-    """Replays a SyntheticTrajectory through the ESKF and measures accuracy.
-
-    The benchmark uses only the ESKF (no full FlightProcessor) for speed.
-    Satellite corrections are injected optionally via sat_correction_fn.
-    """
-
-    def __init__(
-        self,
-        eskf_config: ESKFConfig | None = None,
-        sat_correction_fn: Optional[Callable[[TrajectoryFrame], Optional[np.ndarray]]] = None,
-    ):
-        """
-        Args:
-            eskf_config:        ESKF tuning parameters.
-            sat_correction_fn:  Optional callback(frame) → ENU position or None.
-                                Called on keyframes to inject satellite corrections.
-                                If None, no satellite corrections are applied.
-        """
-        self.eskf_config = eskf_config or ESKFConfig()
-        self.sat_correction_fn = sat_correction_fn
-
-    def run(
-        self,
-        trajectory: list[TrajectoryFrame],
-        origin: GPSPoint,
-        satellite_keyframe_interval: int = 7,
-    ) -> BenchmarkResult:
-        """Replay trajectory frames through ESKF, collect errors and latencies.
-
-        Args:
-            trajectory:                  List of TrajectoryFrame (from SyntheticTrajectory).
-            origin:                      WGS84 reference origin for ENU.
-            satellite_keyframe_interval: Apply satellite correction every N frames.
-        """
-        coord = CoordinateTransformer()
-        flight_id = "__benchmark__"
-        coord.set_enu_origin(flight_id, origin)
-
-        eskf = ESKF(self.eskf_config)
-        # Init at origin with HIGH uncertainty
-        eskf.initialize(np.array([0.0, 0.0, trajectory[0].true_position_enu[2]]),
-                        trajectory[0].timestamp)
-
-        errors_m: list[float] = []
-        latencies_ms: list[float] = []
-        frames_with_estimate = 0
-
-        for frame in trajectory:
-            t_frame_start = time.perf_counter()
-
-            # --- IMU prediction ---
-            for imu in frame.imu_measurements:
-                eskf.predict(imu)
-
-            # --- VO update ---
-            if frame.vo_tracking_good and frame.vo_translation is not None:
-                dt_vo = 1.0 / 0.7  # camera interval
-                eskf.update_vo(frame.vo_translation, dt_vo)
-
-            # --- Satellite update (keyframes) ---
-            if frame.frame_id % satellite_keyframe_interval == 0:
-                sat_pos_enu: Optional[np.ndarray] = None
-                if self.sat_correction_fn is not None:
-                    sat_pos_enu = self.sat_correction_fn(frame)
-                else:
-                    # Default: inject ground-truth position + realistic noise
-                    noise_m = 10.0
-                    sat_pos_enu = (
-                        frame.true_position_enu[:3]
-                        + np.random.randn(3) * noise_m
-                    )
-                    sat_pos_enu[2] = frame.true_position_enu[2]  # keep altitude
-
-                if sat_pos_enu is not None:
-                    # Tell ESKF the measurement noise matches what we inject
-                    eskf.update_satellite(sat_pos_enu, noise_meters=noise_m)
-
-            latency_ms = (time.perf_counter() - t_frame_start) * 1000.0
-            latencies_ms.append(latency_ms)
-
-            # --- Compute horizontal error vs ground truth ---
-            if eskf.initialized and eskf._nominal_state is not None:
-                est_pos = eskf._nominal_state["position"]
-                true_pos = frame.true_position_enu
-                horiz_error = float(np.linalg.norm(est_pos[:2] - true_pos[:2]))
-                errors_m.append(horiz_error)
-                frames_with_estimate += 1
-            else:
-                errors_m.append(float("inf"))
-
-        return BenchmarkResult(
-            errors_m=errors_m,
-            latencies_ms=latencies_ms,
-            frames_total=len(trajectory),
-            frames_with_good_estimate=frames_with_estimate,
-        )
-
-    def run_vo_drift_test(
-        self,
-        trajectory_length_m: float = 1000.0,
-        speed_mps: float = 20.0,
-    ) -> float:
-        """Measure VO drift over a straight segment with NO satellite correction.
-
-        Returns final horizontal position error in metres.
-        Per solution.md, this should be < 100m over 1km.
-        """
-        fps = 0.7
-        num_frames = max(10, int(trajectory_length_m / speed_mps * fps))
-        cfg = SyntheticTrajectoryConfig(
-            speed_mps=speed_mps,
-            heading_deg=0.0,   # straight North
-            camera_fps=fps,
-            num_frames=num_frames,
-            vo_noise_m=0.3,    # cuVSLAM-grade VO noise
-        )
-        traj_gen = SyntheticTrajectory(cfg)
-        frames = traj_gen.generate()
-
-        # No satellite corrections
-        benchmark_no_sat = AccuracyBenchmark(
-            eskf_config=self.eskf_config,
-            sat_correction_fn=lambda _: None,  # suppress all satellite updates
-        )
-        result = benchmark_no_sat.run(frames, cfg.origin, satellite_keyframe_interval=9999)
-        # Return final-frame error
-        return result.errors_m[-1] if result.errors_m else float("inf")
+"""Legacy import path. Phase 1 shim — code lives in testing/benchmark.py."""
+from gps_denied.testing.benchmark import (  # noqa: F401
+    AccuracyBenchmark,
+    BenchmarkResult,
+    SyntheticTrajectory,
+    SyntheticTrajectoryConfig,
+    TrajectoryFrame,
+)

src/gps_denied/core/chunk_manager.py

@@ -2,8 +2,7 @@
 
 import logging
 import uuid
-from abc import ABC, abstractmethod
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Protocol, runtime_checkable
 
 from gps_denied.core.graph import IFactorGraphOptimizer
 from gps_denied.schemas.chunk import ChunkHandle, ChunkStatus
@@ -12,30 +11,25 @@ from gps_denied.schemas.metric import Sim3Transform
 logger = logging.getLogger(__name__)
 
 
-class IRouteChunkManager(ABC):
-    @abstractmethod
+@runtime_checkable
+class IRouteChunkManager(Protocol):
     def create_new_chunk(self, flight_id: str, start_frame_id: int) -> ChunkHandle:
-        pass
+        ...
 
-    @abstractmethod
     def get_active_chunk(self, flight_id: str) -> Optional[ChunkHandle]:
-        pass
+        ...
 
-    @abstractmethod
     def get_all_chunks(self, flight_id: str) -> List[ChunkHandle]:
-        pass
+        ...
 
-    @abstractmethod
     def add_frame_to_chunk(self, flight_id: str, frame_id: int) -> bool:
-        pass
+        ...
 
-    @abstractmethod
     def update_chunk_status(self, flight_id: str, chunk_id: str, status: ChunkStatus) -> bool:
-        pass
+        ...
 
-    @abstractmethod
     def merge_chunks(self, flight_id: str, new_chunk_id: str, main_chunk_id: str, transform: Sim3Transform) -> bool:
-        pass
+        ...
 
 
 class RouteChunkManager(IRouteChunkManager):

src/gps_denied/core/factor_graph.py

@@ -0,0 +1,350 @@
+"""Factor Graph Optimizer (Component F10)."""
+
+import logging
+from datetime import datetime, timezone
+from typing import Dict, Protocol, runtime_checkable
+
+import numpy as np
+
+try:
+    import gtsam
+    HAS_GTSAM = True
+except ImportError:
+    HAS_GTSAM = False
+
+from gps_denied.schemas import GPSPoint
+from gps_denied.schemas.graph import FactorGraphConfig, OptimizationResult, Pose
+from gps_denied.schemas.metric import Sim3Transform
+from gps_denied.schemas.vo import RelativePose
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class IFactorGraphOptimizer(Protocol):
+    """GTSAM-based factor graph optimizer."""
+
+    def add_relative_factor(self, flight_id: str, frame_i: int, frame_j: int, relative_pose: RelativePose, covariance: np.ndarray) -> bool:
+        ...
+
+    def add_absolute_factor(self, flight_id: str, frame_id: int, gps: GPSPoint, covariance: np.ndarray, is_user_anchor: bool) -> bool:
+        ...
+
+    def add_altitude_prior(self, flight_id: str, frame_id: int, altitude: float, covariance: float) -> bool:
+        ...
+
+    def optimize(self, flight_id: str, iterations: int) -> OptimizationResult:
+        ...
+
+    def get_trajectory(self, flight_id: str) -> Dict[int, Pose]:
+        ...
+
+    def get_marginal_covariance(self, flight_id: str, frame_id: int) -> np.ndarray:
+        ...
+
+    def create_chunk_subgraph(self, flight_id: str, chunk_id: str, start_frame_id: int) -> bool:
+        ...
+
+    def add_relative_factor_to_chunk(self, flight_id: str, chunk_id: str, frame_i: int, frame_j: int, relative_pose: RelativePose, covariance: np.ndarray) -> bool:
+        ...
+
+    def add_chunk_anchor(self, flight_id: str, chunk_id: str, frame_id: int, gps: GPSPoint, covariance: np.ndarray) -> bool:
+        ...
+
+    def merge_chunk_subgraphs(self, flight_id: str, new_chunk_id: str, main_chunk_id: str, transform: Sim3Transform) -> bool:
+        ...
+
+    def get_chunk_trajectory(self, flight_id: str, chunk_id: str) -> Dict[int, Pose]:
+        ...
+
+    def optimize_chunk(self, flight_id: str, chunk_id: str, iterations: int) -> OptimizationResult:
+        ...
+
+    def optimize_global(self, flight_id: str, iterations: int) -> OptimizationResult:
+        ...
+
+    def delete_flight_graph(self, flight_id: str) -> bool:
+        ...
+
+
+class FactorGraphOptimizer(IFactorGraphOptimizer):
+    """Implementation of F10 Factor Graph using GTSAM or Mock."""
+
+    def __init__(self, config: FactorGraphConfig):
+        self.config = config
+        # Keyed by flight_id
+        self._flights_state: Dict[str, dict] = {}
+        # Keyed by chunk_id
+        self._chunks_state: Dict[str, dict] = {}
+        # Per-flight ENU origin (set from first absolute GPS factor)
+        self._enu_origins: Dict[str, GPSPoint] = {}
+
+    def _init_flight(self, flight_id: str):
+        if flight_id not in self._flights_state:
+            self._flights_state[flight_id] = {
+                "graph": gtsam.NonlinearFactorGraph() if HAS_GTSAM else None,
+                "initial": gtsam.Values() if HAS_GTSAM else None,
+                "isam": gtsam.ISAM2() if HAS_GTSAM else None,
+                "poses": {},
+                "dirty": False
+            }
+
+    def _init_chunk(self, chunk_id: str):
+        if chunk_id not in self._chunks_state:
+            self._chunks_state[chunk_id] = {
+                "graph": gtsam.NonlinearFactorGraph() if HAS_GTSAM else None,
+                "initial": gtsam.Values() if HAS_GTSAM else None,
+                "isam": gtsam.ISAM2() if HAS_GTSAM else None,
+                "poses": {},
+                "dirty": False
+            }
+
+    # ================== MOCK IMPLEMENTATION ====================
+    # As GTSAM Python bindings can be extremely context-dependent and
+    # require proper ENU translation logic, we use an advanced Mock
+    # that satisfies the architectural design and typing for the backend.
+
+    def add_relative_factor(self, flight_id: str, frame_i: int, frame_j: int, relative_pose: RelativePose, covariance: np.ndarray) -> bool:
+        self._init_flight(flight_id)
+        state = self._flights_state[flight_id]
+
+        # --- Mock: propagate position chain ---
+        if frame_i in state["poses"]:
+            prev_pose = state["poses"][frame_i]
+            new_pos = prev_pose.position + relative_pose.translation
+            state["poses"][frame_j] = Pose(
+                frame_id=frame_j,
+                position=new_pos,
+                orientation=np.eye(3),
+                timestamp=datetime.now(timezone.utc),
+                covariance=np.eye(6),
+            )
+            state["dirty"] = True
+        else:
+            return False
+
+        # --- GTSAM: add BetweenFactorPose3 ---
+        if HAS_GTSAM and state["graph"] is not None:
+            try:
+                cov6 = covariance if covariance.shape == (6, 6) else np.eye(6)
+                noise = gtsam.noiseModel.Gaussian.Covariance(cov6)
+                key_i = gtsam.symbol("x", frame_i)
+                key_j = gtsam.symbol("x", frame_j)
+                t = relative_pose.translation
+                between = gtsam.Pose3(gtsam.Rot3(), gtsam.Point3(float(t[0]), float(t[1]), float(t[2])))
+                state["graph"].add(gtsam.BetweenFactorPose3(key_i, key_j, between, noise))
+                if not state["initial"].exists(key_j):
+                    if state["initial"].exists(key_i):
+                        prev = state["initial"].atPose3(key_i)
+                        pt = prev.translation()
+                        new_t = gtsam.Point3(pt[0] + t[0], pt[1] + t[1], pt[2] + t[2])
+                    else:
+                        new_t = gtsam.Point3(float(t[0]), float(t[1]), float(t[2]))
+                    state["initial"].insert(key_j, gtsam.Pose3(gtsam.Rot3(), new_t))
+            except Exception as exc:
+                logger.debug("GTSAM add_relative_factor failed: %s", exc)
+
+        return True
+
+    def _gps_to_enu(self, flight_id: str, gps: GPSPoint) -> np.ndarray:
+        """Convert GPS to local ENU using per-flight origin."""
+        origin = self._enu_origins.get(flight_id)
+        if origin is None:
+            # First GPS factor sets the origin
+            self._enu_origins[flight_id] = gps
+            return np.zeros(3)
+        enu_x = (gps.lon - origin.lon) * 111000 * np.cos(np.radians(origin.lat))
+        enu_y = (gps.lat - origin.lat) * 111000
+        return np.array([enu_x, enu_y, 0.0])
+
+    def add_absolute_factor(self, flight_id: str, frame_id: int, gps: GPSPoint, covariance: np.ndarray, is_user_anchor: bool) -> bool:
+        self._init_flight(flight_id)
+        state = self._flights_state[flight_id]
+
+        enu = self._gps_to_enu(flight_id, gps)
+
+        # --- Mock: update pose position ---
+        if frame_id in state["poses"]:
+            state["poses"][frame_id].position = enu
+            state["dirty"] = True
+        else:
+            return False
+
+        # --- GTSAM: add PriorFactorPose3 ---
+        if HAS_GTSAM and state["graph"] is not None:
+            try:
+                cov6 = covariance if covariance.shape == (6, 6) else np.eye(6)
+                noise = gtsam.noiseModel.Gaussian.Covariance(cov6)
+                key = gtsam.symbol("x", frame_id)
+                prior = gtsam.Pose3(gtsam.Rot3(), gtsam.Point3(float(enu[0]), float(enu[1]), float(enu[2])))
+                state["graph"].add(gtsam.PriorFactorPose3(key, prior, noise))
+                if not state["initial"].exists(key):
+                    state["initial"].insert(key, prior)
+            except Exception as exc:
+                logger.debug("GTSAM add_absolute_factor failed: %s", exc)
+
+        return True
+
+    def add_altitude_prior(self, flight_id: str, frame_id: int, altitude: float, covariance: float) -> bool:
+        self._init_flight(flight_id)
+        state = self._flights_state[flight_id]
+
+        if frame_id in state["poses"]:
+            state["poses"][frame_id].position = np.array([
+                state["poses"][frame_id].position[0],
+                state["poses"][frame_id].position[1],
+                altitude,
+            ])
+            state["dirty"] = True
+            return True
+        return False
+
+    def optimize(self, flight_id: str, iterations: int) -> OptimizationResult:
+        self._init_flight(flight_id)
+        state = self._flights_state[flight_id]
+
+        # --- PIPE-03: Real GTSAM ISAM2 update when available ---
+        if HAS_GTSAM and state["dirty"] and state["graph"] is not None:
+            try:
+                state["isam"].update(state["graph"], state["initial"])
+                estimate = state["isam"].calculateEstimate()
+                for fid in list(state["poses"].keys()):
+                    key = gtsam.symbol("x", fid)
+                    if estimate.exists(key):
+                        pose = estimate.atPose3(key)
+                        t = pose.translation()
+                        state["poses"][fid].position = np.array([t[0], t[1], t[2]])
+                        state["poses"][fid].orientation = np.array(pose.rotation().matrix())
+                # Reset for next incremental batch
+                state["graph"] = gtsam.NonlinearFactorGraph()
+                state["initial"] = gtsam.Values()
+            except Exception as exc:
+                logger.warning("GTSAM ISAM2 update failed: %s", exc)
+
+        state["dirty"] = False
+        return OptimizationResult(
+            converged=True,
+            final_error=0.1,
+            iterations_used=iterations,
+            optimized_frames=list(state["poses"].keys()),
+            mean_reprojection_error=0.5,
+        )
+
+    def get_trajectory(self, flight_id: str) -> Dict[int, Pose]:
+        if flight_id not in self._flights_state:
+            return {}
+        return self._flights_state[flight_id]["poses"]
+
+    def get_marginal_covariance(self, flight_id: str, frame_id: int) -> np.ndarray:
+        return np.eye(6)
+
+    # ================== CHUNK OPERATIONS =======================
+
+    def create_chunk_subgraph(self, flight_id: str, chunk_id: str, start_frame_id: int) -> bool:
+        self._init_chunk(chunk_id)
+        state = self._chunks_state[chunk_id]
+
+        state["poses"][start_frame_id] = Pose(
+            frame_id=start_frame_id,
+            position=np.zeros(3),
+            orientation=np.eye(3),
+            timestamp=datetime.now(timezone.utc),
+            covariance=np.eye(6)
+        )
+        return True
+
+    def add_relative_factor_to_chunk(self, flight_id: str, chunk_id: str, frame_i: int, frame_j: int, relative_pose: RelativePose, covariance: np.ndarray) -> bool:
+        if chunk_id not in self._chunks_state:
+            return False
+
+        state = self._chunks_state[chunk_id]
+        if frame_i in state["poses"]:
+            prev_pose = state["poses"][frame_i]
+            new_pos = prev_pose.position + relative_pose.translation
+
+            state["poses"][frame_j] = Pose(
+                frame_id=frame_j,
+                position=new_pos,
+                orientation=np.eye(3),
+                timestamp=datetime.now(timezone.utc),
+                covariance=np.eye(6)
+            )
+            state["dirty"] = True
+            return True
+        return False
+
+    def add_chunk_anchor(self, flight_id: str, chunk_id: str, frame_id: int, gps: GPSPoint, covariance: np.ndarray) -> bool:
+        if chunk_id not in self._chunks_state:
+            return False
+
+        state = self._chunks_state[chunk_id]
+        if frame_id in state["poses"]:
+            enu = self._gps_to_enu(flight_id, gps)
+            state["poses"][frame_id].position = enu
+            state["dirty"] = True
+            return True
+        return False
+
+    def merge_chunk_subgraphs(self, flight_id: str, new_chunk_id: str, main_chunk_id: str, transform: Sim3Transform) -> bool:
+        if new_chunk_id not in self._chunks_state or main_chunk_id not in self._chunks_state:
+            return False
+
+        new_state = self._chunks_state[new_chunk_id]
+        main_state = self._chunks_state[main_chunk_id]
+
+        # Apply Sim(3) transform effectively by copying poses
+        for f_id, p in new_state["poses"].items():
+            # mock sim3 transform
+            idx_pos = (transform.scale * (transform.rotation @ p.position)) + transform.translation
+
+            main_state["poses"][f_id] = Pose(
+                frame_id=f_id,
+                position=idx_pos,
+                orientation=np.eye(3),
+                timestamp=p.timestamp,
+                covariance=p.covariance
+            )
+
+        return True
+
+    def get_chunk_trajectory(self, flight_id: str, chunk_id: str) -> Dict[int, Pose]:
+        if chunk_id not in self._chunks_state:
+            return {}
+        return self._chunks_state[chunk_id]["poses"]
+
+    def optimize_chunk(self, flight_id: str, chunk_id: str, iterations: int) -> OptimizationResult:
+        if chunk_id not in self._chunks_state:
+            return OptimizationResult(converged=False, final_error=99.0, iterations_used=0, optimized_frames=[], mean_reprojection_error=99.0)
+
+        state = self._chunks_state[chunk_id]
+        state["dirty"] = False
+
+        return OptimizationResult(
+            converged=True,
+            final_error=0.1,
+            iterations_used=iterations,
+            optimized_frames=list(state["poses"].keys()),
+            mean_reprojection_error=0.5
+        )
+
+    def optimize_global(self, flight_id: str, iterations: int) -> OptimizationResult:
+        # Optimizes everything
+        self._init_flight(flight_id)
+        state = self._flights_state[flight_id]
+        state["dirty"] = False
+
+        return OptimizationResult(
+            converged=True,
+            final_error=0.1,
+            iterations_used=iterations,
+            optimized_frames=list(state["poses"].keys()),
+            mean_reprojection_error=0.5
+        )
+
+    def delete_flight_graph(self, flight_id: str) -> bool:
+        removed = False
+        if flight_id in self._flights_state:
+            del self._flights_state[flight_id]
+            removed = True
+        self._enu_origins.pop(flight_id, None)
+        return removed

src/gps_denied/core/gpr.py

@@ -1,271 +1,16 @@
-"""Global Place Recognition (Component F08).
+"""Legacy import path for GPR. Phase 1 shim — code lives in components/gpr/."""
+from gps_denied.components.gpr.protocol import (
+    IGlobalPlaceRecognition,  # noqa: F401
+)
+from gps_denied.components.gpr.faiss_gpr import (
+    GlobalPlaceRecognition,
+    _faiss,
+    _FAISS_AVAILABLE,
+)
 
-GPR-01: Loads a real Faiss index from disk when available; numpy-L2 fallback for dev/CI.
-GPR-02: DINOv2/AnyLoc TRT FP16 on Jetson; MockInferenceEngine on dev/CI (via ModelManager).
-GPR-03: Candidates ranked by DINOv2 descriptor similarity (dot-product / L2 distance).
-"""
-
-import json
-import logging
-import os
-from abc import ABC, abstractmethod
-from typing import Dict, List
-
-import numpy as np
-
-from gps_denied.core.models import IModelManager
-from gps_denied.schemas import GPSPoint
-from gps_denied.schemas.gpr import DatabaseMatch, TileCandidate
-from gps_denied.schemas.satellite import TileBounds
-
-logger = logging.getLogger(__name__)
-
-# Attempt to import Faiss (optional — only available on Jetson or with faiss-cpu installed)
-try:
-    import faiss as _faiss  # type: ignore
-    _FAISS_AVAILABLE = True
-    logger.info("Faiss available — real index search enabled")
-except ImportError:
-    _faiss = None  # type: ignore
-    _FAISS_AVAILABLE = False
-    logger.info("Faiss not available — using numpy L2 fallback for GPR")
-
-
-class IGlobalPlaceRecognition(ABC):
-    @abstractmethod
-    def retrieve_candidate_tiles(self, image: np.ndarray, top_k: int) -> List[TileCandidate]:
-        pass
-
-    @abstractmethod
-    def compute_location_descriptor(self, image: np.ndarray) -> np.ndarray:
-        pass
-
-    @abstractmethod
-    def query_database(self, descriptor: np.ndarray, top_k: int) -> List[DatabaseMatch]:
-        pass
-
-    @abstractmethod
-    def rank_candidates(self, candidates: List[TileCandidate]) -> List[TileCandidate]:
-        pass
-
-    @abstractmethod
-    def load_index(self, flight_id: str, index_path: str) -> bool:
-        pass
-
-    @abstractmethod
-    def retrieve_candidate_tiles_for_chunk(self, chunk_images: List[np.ndarray], top_k: int) -> List[TileCandidate]:
-        pass
-
-    @abstractmethod
-    def compute_chunk_descriptor(self, chunk_images: List[np.ndarray]) -> np.ndarray:
-        pass
-
-
-class GlobalPlaceRecognition(IGlobalPlaceRecognition):
-    """AnyLoc-VLAD-DINOv2 coarse localisation component — sprint 1 GPR baseline.
-
-    GPR-01: load_index() tries to open a real Faiss .index file; falls back to
-            a NumPy L2 mock when the file is missing or Faiss is not installed.
-    GPR-02: Descriptor computed via DINOv2 engine (TRT FP16 on Jetson, Mock on
-            dev/CI). INT8 quantization is disabled — broken for ViT on Jetson
-            (NVIDIA/TRT#4348, facebookresearch/dinov2#489).
-    GPR-03: Candidates ranked by descriptor similarity (L2 → converted to [0,1]).
-
-    Selected over NetVLAD (deprecated, −2.4% R@1 on MSLS 2024) and SuperPoint+
-    LightGlue (unvalidated for cross-view UAV↔satellite gap at sprint 1).
-    Stage 2 evaluation: SP+LG+FAISS per _docs/03_backlog/stage2_ideas/.
-    Long-term target: EigenPlaces (ICCV 2023) — cleaner ONNX export.
-
-    Ref: docs/superpowers/specs/2026-04-18-oss-stack-tech-audit-design.md §2.3
-    """
-
-    _DIM = 4096  # DINOv2 VLAD descriptor dimension
-
-    def __init__(self, model_manager: IModelManager):
-        self.model_manager = model_manager
-
-        # Index storage — one of: Faiss index OR numpy matrix
-        self._faiss_index = None          # faiss.IndexFlatIP or similar
-        self._np_descriptors: np.ndarray | None = None   # (N, DIM) fallback
-        self._metadata: Dict[int, dict] = {}
-        self._is_loaded = False
-
-    # ------------------------------------------------------------------
-    # GPR-02: Descriptor extraction via DINOv2
-    # ------------------------------------------------------------------
-
-    def compute_location_descriptor(self, image: np.ndarray) -> np.ndarray:
-        """Run DINOv2 inference and return an L2-normalised descriptor."""
-        engine = self.model_manager.get_inference_engine("DINOv2")
-        desc = engine.infer(image)
-        norm = np.linalg.norm(desc)
-        return desc / max(norm, 1e-12)
-
-    def compute_chunk_descriptor(self, chunk_images: List[np.ndarray]) -> np.ndarray:
-        """Mean-aggregate per-frame DINOv2 descriptors for a chunk."""
-        if not chunk_images:
-            return np.zeros(self._DIM, dtype=np.float32)
-        descs = [self.compute_location_descriptor(img) for img in chunk_images]
-        agg = np.mean(descs, axis=0)
-        return agg / max(np.linalg.norm(agg), 1e-12)
-
-    # ------------------------------------------------------------------
-    # GPR-01: Index loading
-    # ------------------------------------------------------------------
-
-    def load_index(self, flight_id: str, index_path: str) -> bool:
-        """Load a Faiss descriptor index from disk (GPR-01).
-
-        Falls back to a NumPy random-vector mock when:
-          - `index_path` does not exist, OR
-          - Faiss is not installed (dev/CI without faiss-cpu).
-        """
-        logger.info("Loading GPR index for flight=%s path=%s", flight_id, index_path)
-
-        # Try real Faiss load ------------------------------------------------
-        if _FAISS_AVAILABLE and os.path.isfile(index_path):
-            try:
-                self._faiss_index = _faiss.read_index(index_path)
-                # Load companion metadata JSON if present
-                meta_path = os.path.splitext(index_path)[0] + "_meta.json"
-                if os.path.isfile(meta_path):
-                    with open(meta_path) as f:
-                        raw = json.load(f)
-                    self._metadata = {int(k): v for k, v in raw.items()}
-                    # Deserialise GPSPoint / TileBounds from dicts
-                    for idx, m in self._metadata.items():
-                        if isinstance(m.get("gps_center"), dict):
-                            m["gps_center"] = GPSPoint(**m["gps_center"])
-                        if isinstance(m.get("bounds"), dict):
-                            bounds_d = m["bounds"]
-                            for corner in ("nw", "ne", "sw", "se", "center"):
-                                if isinstance(bounds_d.get(corner), dict):
-                                    bounds_d[corner] = GPSPoint(**bounds_d[corner])
-                            m["bounds"] = TileBounds(**bounds_d)
-                else:
-                    self._metadata = self._generate_stub_metadata(self._faiss_index.ntotal)
-                self._is_loaded = True
-                logger.info("Faiss index loaded: %d vectors", self._faiss_index.ntotal)
-                return True
-            except Exception as exc:
-                logger.warning("Faiss load failed (%s) — falling back to numpy mock", exc)
-
-        # NumPy mock fallback ------------------------------------------------
-        logger.info("GPR: using numpy mock index (dev/CI mode)")
-        db_size = 1000
-        vecs = np.random.rand(db_size, self._DIM).astype(np.float32)
-        norms = np.linalg.norm(vecs, axis=1, keepdims=True)
-        self._np_descriptors = vecs / np.maximum(norms, 1e-12)
-        self._metadata = self._generate_stub_metadata(db_size)
-        self._is_loaded = True
-        return True
-
-    @staticmethod
-    def _generate_stub_metadata(n: int) -> Dict[int, dict]:
-        """Generate placeholder tile metadata for dev/CI mock index."""
-        meta: Dict[int, dict] = {}
-        for i in range(n):
-            meta[i] = {
-                "tile_id": f"tile_{i:06d}",
-                "gps_center": GPSPoint(lat=49.0 + np.random.rand(), lon=32.0 + np.random.rand()),
-                "bounds": TileBounds(
-                    nw=GPSPoint(lat=49.1, lon=32.0),
-                    ne=GPSPoint(lat=49.1, lon=32.1),
-                    sw=GPSPoint(lat=49.0, lon=32.0),
-                    se=GPSPoint(lat=49.0, lon=32.1),
-                    center=GPSPoint(lat=49.05, lon=32.05),
-                    gsd=0.6,
-                ),
-            }
-        return meta
-
-    # ------------------------------------------------------------------
-    # GPR-03: Similarity search ranked by descriptor distance
-    # ------------------------------------------------------------------
-
-    def query_database(self, descriptor: np.ndarray, top_k: int) -> List[DatabaseMatch]:
-        """Search the index for the top-k most similar tiles.
-
-        Uses Faiss when loaded, numpy L2 otherwise.
-        Results are sorted by ascending L2 distance (= descending similarity).
-        """
-        if not self._is_loaded:
-            logger.error("GPR index not loaded — call load_index() first.")
-            return []
-
-        q = descriptor.astype(np.float32).reshape(1, -1)
-
-        # Faiss path
-        if self._faiss_index is not None:
-            try:
-                distances, indices = self._faiss_index.search(q, top_k)
-                results = []
-                for dist, idx in zip(distances[0], indices[0]):
-                    if idx < 0:
-                        continue
-                    sim = 1.0 / (1.0 + float(dist))
-                    meta = self._metadata.get(int(idx), {"tile_id": f"tile_{idx}"})
-                    results.append(DatabaseMatch(
-                        index=int(idx),
-                        tile_id=meta.get("tile_id", str(idx)),
-                        distance=float(dist),
-                        similarity_score=sim,
-                    ))
-                return results
-            except Exception as exc:
-                logger.warning("Faiss search failed: %s", exc)
-
-        # NumPy path
-        if self._np_descriptors is None:
-            return []
-        diff = self._np_descriptors - q  # (N, DIM)
-        distances = np.sum(diff ** 2, axis=1)
-        top_indices = np.argsort(distances)[:top_k]
-
-        results = []
-        for idx in top_indices:
-            dist = float(distances[idx])
-            sim = 1.0 / (1.0 + dist)
-            meta = self._metadata.get(int(idx), {"tile_id": f"tile_{idx}"})
-            results.append(DatabaseMatch(
-                index=int(idx),
-                tile_id=meta.get("tile_id", str(idx)),
-                distance=dist,
-                similarity_score=sim,
-            ))
-        return results
-
-    def rank_candidates(self, candidates: List[TileCandidate]) -> List[TileCandidate]:
-        """Sort candidates by descriptor similarity (descending) — GPR-03."""
-        return sorted(candidates, key=lambda c: c.similarity_score, reverse=True)
-
-    def _matches_to_candidates(self, matches: List[DatabaseMatch]) -> List[TileCandidate]:
-        candidates = []
-        for rank, match in enumerate(matches, 1):
-            meta = self._metadata.get(match.index, {})
-            gps = meta.get("gps_center", GPSPoint(lat=49.0, lon=32.0))
-            bounds = meta.get("bounds", TileBounds(
-                nw=GPSPoint(lat=49.1, lon=32.0), ne=GPSPoint(lat=49.1, lon=32.1),
-                sw=GPSPoint(lat=49.0, lon=32.0), se=GPSPoint(lat=49.0, lon=32.1),
-                center=GPSPoint(lat=49.05, lon=32.05), gsd=0.6,
-            ))
-            candidates.append(TileCandidate(
-                tile_id=match.tile_id,
-                gps_center=gps,
-                bounds=bounds,
-                similarity_score=match.similarity_score,
-                rank=rank,
-            ))
-        return self.rank_candidates(candidates)
-
-    def retrieve_candidate_tiles(self, image: np.ndarray, top_k: int = 5) -> List[TileCandidate]:
-        desc = self.compute_location_descriptor(image)
-        matches = self.query_database(desc, top_k)
-        return self._matches_to_candidates(matches)
-
-    def retrieve_candidate_tiles_for_chunk(
-        self, chunk_images: List[np.ndarray], top_k: int = 5
-    ) -> List[TileCandidate]:
-        desc = self.compute_chunk_descriptor(chunk_images)
-        matches = self.query_database(desc, top_k)
-        return self._matches_to_candidates(matches)
+__all__ = [
+    "GlobalPlaceRecognition",
+    "IGlobalPlaceRecognition",
+    "_faiss",
+    "_FAISS_AVAILABLE",
+]

src/gps_denied/core/graph.py

@@ -1,364 +1,5 @@
-"""Factor Graph Optimizer (Component F10)."""
-
-import logging
-from abc import ABC, abstractmethod
-from datetime import datetime, timezone
-from typing import Dict
-
-import numpy as np
-
-try:
-    import gtsam
-    HAS_GTSAM = True
-except ImportError:
-    HAS_GTSAM = False
-
-from gps_denied.schemas import GPSPoint
-from gps_denied.schemas.graph import FactorGraphConfig, OptimizationResult, Pose
-from gps_denied.schemas.metric import Sim3Transform
-from gps_denied.schemas.vo import RelativePose
-
-logger = logging.getLogger(__name__)
-
-
-class IFactorGraphOptimizer(ABC):
-    """GTSAM-based factor graph optimizer."""
-
-    @abstractmethod
-    def add_relative_factor(self, flight_id: str, frame_i: int, frame_j: int, relative_pose: RelativePose, covariance: np.ndarray) -> bool:
-        pass
-
-    @abstractmethod
-    def add_absolute_factor(self, flight_id: str, frame_id: int, gps: GPSPoint, covariance: np.ndarray, is_user_anchor: bool) -> bool:
-        pass
-
-    @abstractmethod
-    def add_altitude_prior(self, flight_id: str, frame_id: int, altitude: float, covariance: float) -> bool:
-        pass
-
-    @abstractmethod
-    def optimize(self, flight_id: str, iterations: int) -> OptimizationResult:
-        pass
-
-    @abstractmethod
-    def get_trajectory(self, flight_id: str) -> Dict[int, Pose]:
-        pass
-
-    @abstractmethod
-    def get_marginal_covariance(self, flight_id: str, frame_id: int) -> np.ndarray:
-        pass
-
-    @abstractmethod
-    def create_chunk_subgraph(self, flight_id: str, chunk_id: str, start_frame_id: int) -> bool:
-        pass
-
-    @abstractmethod
-    def add_relative_factor_to_chunk(self, flight_id: str, chunk_id: str, frame_i: int, frame_j: int, relative_pose: RelativePose, covariance: np.ndarray) -> bool:
-        pass
-
-    @abstractmethod
-    def add_chunk_anchor(self, flight_id: str, chunk_id: str, frame_id: int, gps: GPSPoint, covariance: np.ndarray) -> bool:
-        pass
-
-    @abstractmethod
-    def merge_chunk_subgraphs(self, flight_id: str, new_chunk_id: str, main_chunk_id: str, transform: Sim3Transform) -> bool:
-        pass
-
-    @abstractmethod
-    def get_chunk_trajectory(self, flight_id: str, chunk_id: str) -> Dict[int, Pose]:
-        pass
-
-    @abstractmethod
-    def optimize_chunk(self, flight_id: str, chunk_id: str, iterations: int) -> OptimizationResult:
-        pass
-
-    @abstractmethod
-    def optimize_global(self, flight_id: str, iterations: int) -> OptimizationResult:
-        pass
-
-    @abstractmethod
-    def delete_flight_graph(self, flight_id: str) -> bool:
-        pass
-
-
-class FactorGraphOptimizer(IFactorGraphOptimizer):
-    """Implementation of F10 Factor Graph using GTSAM or Mock."""
-
-    def __init__(self, config: FactorGraphConfig):
-        self.config = config
-        # Keyed by flight_id
-        self._flights_state: Dict[str, dict] = {}
-        # Keyed by chunk_id
-        self._chunks_state: Dict[str, dict] = {}
-        # Per-flight ENU origin (set from first absolute GPS factor)
-        self._enu_origins: Dict[str, GPSPoint] = {}
-
-    def _init_flight(self, flight_id: str):
-        if flight_id not in self._flights_state:
-            self._flights_state[flight_id] = {
-                "graph": gtsam.NonlinearFactorGraph() if HAS_GTSAM else None,
-                "initial": gtsam.Values() if HAS_GTSAM else None,
-                "isam": gtsam.ISAM2() if HAS_GTSAM else None,
-                "poses": {},
-                "dirty": False
-            }
-
-    def _init_chunk(self, chunk_id: str):
-        if chunk_id not in self._chunks_state:
-            self._chunks_state[chunk_id] = {
-                "graph": gtsam.NonlinearFactorGraph() if HAS_GTSAM else None,
-                "initial": gtsam.Values() if HAS_GTSAM else None,
-                "isam": gtsam.ISAM2() if HAS_GTSAM else None,
-                "poses": {},
-                "dirty": False
-            }
-
-    # ================== MOCK IMPLEMENTATION ====================
-    # As GTSAM Python bindings can be extremely context-dependent and
-    # require proper ENU translation logic, we use an advanced Mock
-    # that satisfies the architectural design and typing for the backend.
-
-    def add_relative_factor(self, flight_id: str, frame_i: int, frame_j: int, relative_pose: RelativePose, covariance: np.ndarray) -> bool:
-        self._init_flight(flight_id)
-        state = self._flights_state[flight_id]
-
-        # --- Mock: propagate position chain ---
-        if frame_i in state["poses"]:
-            prev_pose = state["poses"][frame_i]
-            new_pos = prev_pose.position + relative_pose.translation
-            state["poses"][frame_j] = Pose(
-                frame_id=frame_j,
-                position=new_pos,
-                orientation=np.eye(3),
-                timestamp=datetime.now(timezone.utc),
-                covariance=np.eye(6),
-            )
-            state["dirty"] = True
-        else:
-            return False
-
-        # --- GTSAM: add BetweenFactorPose3 ---
-        if HAS_GTSAM and state["graph"] is not None:
-            try:
-                cov6 = covariance if covariance.shape == (6, 6) else np.eye(6)
-                noise = gtsam.noiseModel.Gaussian.Covariance(cov6)
-                key_i = gtsam.symbol("x", frame_i)
-                key_j = gtsam.symbol("x", frame_j)
-                t = relative_pose.translation
-                between = gtsam.Pose3(gtsam.Rot3(), gtsam.Point3(float(t[0]), float(t[1]), float(t[2])))
-                state["graph"].add(gtsam.BetweenFactorPose3(key_i, key_j, between, noise))
-                if not state["initial"].exists(key_j):
-                    if state["initial"].exists(key_i):
-                        prev = state["initial"].atPose3(key_i)
-                        pt = prev.translation()
-                        new_t = gtsam.Point3(pt[0] + t[0], pt[1] + t[1], pt[2] + t[2])
-                    else:
-                        new_t = gtsam.Point3(float(t[0]), float(t[1]), float(t[2]))
-                    state["initial"].insert(key_j, gtsam.Pose3(gtsam.Rot3(), new_t))
-            except Exception as exc:
-                logger.debug("GTSAM add_relative_factor failed: %s", exc)
-
-        return True
-
-    def _gps_to_enu(self, flight_id: str, gps: GPSPoint) -> np.ndarray:
-        """Convert GPS to local ENU using per-flight origin."""
-        origin = self._enu_origins.get(flight_id)
-        if origin is None:
-            # First GPS factor sets the origin
-            self._enu_origins[flight_id] = gps
-            return np.zeros(3)
-        enu_x = (gps.lon - origin.lon) * 111000 * np.cos(np.radians(origin.lat))
-        enu_y = (gps.lat - origin.lat) * 111000
-        return np.array([enu_x, enu_y, 0.0])
-
-    def add_absolute_factor(self, flight_id: str, frame_id: int, gps: GPSPoint, covariance: np.ndarray, is_user_anchor: bool) -> bool:
-        self._init_flight(flight_id)
-        state = self._flights_state[flight_id]
-
-        enu = self._gps_to_enu(flight_id, gps)
-
-        # --- Mock: update pose position ---
-        if frame_id in state["poses"]:
-            state["poses"][frame_id].position = enu
-            state["dirty"] = True
-        else:
-            return False
-
-        # --- GTSAM: add PriorFactorPose3 ---
-        if HAS_GTSAM and state["graph"] is not None:
-            try:
-                cov6 = covariance if covariance.shape == (6, 6) else np.eye(6)
-                noise = gtsam.noiseModel.Gaussian.Covariance(cov6)
-                key = gtsam.symbol("x", frame_id)
-                prior = gtsam.Pose3(gtsam.Rot3(), gtsam.Point3(float(enu[0]), float(enu[1]), float(enu[2])))
-                state["graph"].add(gtsam.PriorFactorPose3(key, prior, noise))
-                if not state["initial"].exists(key):
-                    state["initial"].insert(key, prior)
-            except Exception as exc:
-                logger.debug("GTSAM add_absolute_factor failed: %s", exc)
-
-        return True
-
-    def add_altitude_prior(self, flight_id: str, frame_id: int, altitude: float, covariance: float) -> bool:
-        self._init_flight(flight_id)
-        state = self._flights_state[flight_id]
-
-        if frame_id in state["poses"]:
-            state["poses"][frame_id].position = np.array([
-                state["poses"][frame_id].position[0],
-                state["poses"][frame_id].position[1],
-                altitude,
-            ])
-            state["dirty"] = True
-            return True
-        return False
-
-    def optimize(self, flight_id: str, iterations: int) -> OptimizationResult:
-        self._init_flight(flight_id)
-        state = self._flights_state[flight_id]
-
-        # --- PIPE-03: Real GTSAM ISAM2 update when available ---
-        if HAS_GTSAM and state["dirty"] and state["graph"] is not None:
-            try:
-                state["isam"].update(state["graph"], state["initial"])
-                estimate = state["isam"].calculateEstimate()
-                for fid in list(state["poses"].keys()):
-                    key = gtsam.symbol("x", fid)
-                    if estimate.exists(key):
-                        pose = estimate.atPose3(key)
-                        t = pose.translation()
-                        state["poses"][fid].position = np.array([t[0], t[1], t[2]])
-                        state["poses"][fid].orientation = np.array(pose.rotation().matrix())
-                # Reset for next incremental batch
-                state["graph"] = gtsam.NonlinearFactorGraph()
-                state["initial"] = gtsam.Values()
-            except Exception as exc:
-                logger.warning("GTSAM ISAM2 update failed: %s", exc)
-
-        state["dirty"] = False
-        return OptimizationResult(
-            converged=True,
-            final_error=0.1,
-            iterations_used=iterations,
-            optimized_frames=list(state["poses"].keys()),
-            mean_reprojection_error=0.5,
-        )
-
-    def get_trajectory(self, flight_id: str) -> Dict[int, Pose]:
-        if flight_id not in self._flights_state:
-            return {}
-        return self._flights_state[flight_id]["poses"]
-
-    def get_marginal_covariance(self, flight_id: str, frame_id: int) -> np.ndarray:
-        return np.eye(6)
-
-    # ================== CHUNK OPERATIONS =======================
-
-    def create_chunk_subgraph(self, flight_id: str, chunk_id: str, start_frame_id: int) -> bool:
-        self._init_chunk(chunk_id)
-        state = self._chunks_state[chunk_id]
-
-        state["poses"][start_frame_id] = Pose(
-            frame_id=start_frame_id,
-            position=np.zeros(3),
-            orientation=np.eye(3),
-            timestamp=datetime.now(timezone.utc),
-            covariance=np.eye(6)
-        )
-        return True
-
-    def add_relative_factor_to_chunk(self, flight_id: str, chunk_id: str, frame_i: int, frame_j: int, relative_pose: RelativePose, covariance: np.ndarray) -> bool:
-        if chunk_id not in self._chunks_state:
-            return False
-
-        state = self._chunks_state[chunk_id]
-        if frame_i in state["poses"]:
-            prev_pose = state["poses"][frame_i]
-            new_pos = prev_pose.position + relative_pose.translation
-
-            state["poses"][frame_j] = Pose(
-                frame_id=frame_j,
-                position=new_pos,
-                orientation=np.eye(3),
-                timestamp=datetime.now(timezone.utc),
-                covariance=np.eye(6)
-            )
-            state["dirty"] = True
-            return True
-        return False
-
-    def add_chunk_anchor(self, flight_id: str, chunk_id: str, frame_id: int, gps: GPSPoint, covariance: np.ndarray) -> bool:
-        if chunk_id not in self._chunks_state:
-            return False
-
-        state = self._chunks_state[chunk_id]
-        if frame_id in state["poses"]:
-            enu = self._gps_to_enu(flight_id, gps)
-            state["poses"][frame_id].position = enu
-            state["dirty"] = True
-            return True
-        return False
-
-    def merge_chunk_subgraphs(self, flight_id: str, new_chunk_id: str, main_chunk_id: str, transform: Sim3Transform) -> bool:
-        if new_chunk_id not in self._chunks_state or main_chunk_id not in self._chunks_state:
-            return False
-
-        new_state = self._chunks_state[new_chunk_id]
-        main_state = self._chunks_state[main_chunk_id]
-
-        # Apply Sim(3) transform effectively by copying poses
-        for f_id, p in new_state["poses"].items():
-            # mock sim3 transform
-            idx_pos = (transform.scale * (transform.rotation @ p.position)) + transform.translation
-
-            main_state["poses"][f_id] = Pose(
-                frame_id=f_id,
-                position=idx_pos,
-                orientation=np.eye(3),
-                timestamp=p.timestamp,
-                covariance=p.covariance
-            )
-
-        return True
-
-    def get_chunk_trajectory(self, flight_id: str, chunk_id: str) -> Dict[int, Pose]:
-        if chunk_id not in self._chunks_state:
-            return {}
-        return self._chunks_state[chunk_id]["poses"]
-
-    def optimize_chunk(self, flight_id: str, chunk_id: str, iterations: int) -> OptimizationResult:
-        if chunk_id not in self._chunks_state:
-            return OptimizationResult(converged=False, final_error=99.0, iterations_used=0, optimized_frames=[], mean_reprojection_error=99.0)
-
-        state = self._chunks_state[chunk_id]
-        state["dirty"] = False
-
-        return OptimizationResult(
-            converged=True,
-            final_error=0.1,
-            iterations_used=iterations,
-            optimized_frames=list(state["poses"].keys()),
-            mean_reprojection_error=0.5
-        )
-
-    def optimize_global(self, flight_id: str, iterations: int) -> OptimizationResult:
-        # Optimizes everything
-        self._init_flight(flight_id)
-        state = self._flights_state[flight_id]
-        state["dirty"] = False
-
-        return OptimizationResult(
-            converged=True,
-            final_error=0.1,
-            iterations_used=iterations,
-            optimized_frames=list(state["poses"].keys()),
-            mean_reprojection_error=0.5
-        )
-
-    def delete_flight_graph(self, flight_id: str) -> bool:
-        removed = False
-        if flight_id in self._flights_state:
-            del self._flights_state[flight_id]
-            removed = True
-        self._enu_origins.pop(flight_id, None)
-        return removed
+"""Legacy import path. Phase 1 shim — code lives in core/factor_graph.py."""
+from gps_denied.core.factor_graph import (  # noqa: F401
+    IFactorGraphOptimizer,
+    FactorGraphOptimizer,
+)

src/gps_denied/core/mavlink.py

@@ -1,483 +1,29 @@
-"""MAVLink I/O Bridge (Phase 4).
+"""Legacy import path. Phase 1 shim — code lives in components/mavlink_io/.
 
-MAV-01: Sends GPS_INPUT (#233) over UART at 5–10 Hz via pymavlink.
-MAV-02: Maps ESKF state + covariance → all GPS_INPUT fields.
-MAV-03: Receives ATTITUDE / RAW_IMU, converts to IMUMeasurement, feeds ESKF.
-MAV-04: Detects 3 consecutive frames with no position → sends NAMED_VALUE_FLOAT
-        re-localisation request to ground station.
-MAV-05: Telemetry at 1 Hz (confidence + drift) via NAMED_VALUE_FLOAT.
-
-On dev/CI (pymavlink absent) every send/receive call silently no-ops via
-MockMAVConnection so the rest of the pipeline remains testable.
+CRITICAL: tests/test_mavlink.py and tests/test_gps_input_encoding.py import
+private helpers from this path. Per PATTERNS.md §6.2, the underscore names
+MUST be re-exported here verbatim or 12+ tests break.
 """
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import math
-import time
-from typing import Callable, Optional
-
-import numpy as np
-
-from gps_denied.schemas import GPSPoint
-from gps_denied.schemas.eskf import ConfidenceTier, ESKFState, IMUMeasurement
-from gps_denied.schemas.mavlink import (
-    GPSInputMessage,
-    RelocalizationRequest,
-    TelemetryMessage,
+from gps_denied.components.mavlink_io.protocol import (  # noqa: F401
+    MAVLinkBridgeProtocol,
+)
+from gps_denied.components.mavlink_io.pymavlink_bridge import (  # noqa: F401
+    MAVLinkBridge,
+    _PYMAVLINK_AVAILABLE,
+    _unix_to_gps_time,
+    _confidence_to_fix_type,
+    _eskf_to_gps_input,
+)
+from gps_denied.components.mavlink_io.mock_mavlink import (  # noqa: F401
+    MockMAVConnection,
 )
 
-logger = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# pymavlink conditional import
-# ---------------------------------------------------------------------------
-try:
-    from pymavlink import mavutil as _mavutil  # type: ignore
-    _PYMAVLINK_AVAILABLE = True
-    logger.info("pymavlink available — real MAVLink connection enabled")
-except ImportError:
-    _mavutil = None  # type: ignore
-    _PYMAVLINK_AVAILABLE = False
-    logger.info("pymavlink not available — using MockMAVConnection (dev/CI mode)")
-
-# GPS epoch offset from Unix epoch (seconds)
-_GPS_EPOCH_OFFSET = 315_964_800
-
-
-# ---------------------------------------------------------------------------
-# GPS time helpers (MAV-02)
-# ---------------------------------------------------------------------------
-
-def _unix_to_gps_time(unix_s: float) -> tuple[int, int]:
-    """Convert Unix timestamp to (GPS_week, GPS_ms_of_week)."""
-    gps_s = unix_s - _GPS_EPOCH_OFFSET
-    gps_s = max(0.0, gps_s)
-    week = int(gps_s // (7 * 86400))
-    ms_of_week = int((gps_s % (7 * 86400)) * 1000)
-    return week, ms_of_week
-
-
-def _confidence_to_fix_type(confidence: ConfidenceTier) -> int:
-    """Map ESKF confidence tier to GPS_INPUT fix_type (MAV-02)."""
-    return {
-        ConfidenceTier.HIGH: 3,    # 3D fix
-        ConfidenceTier.MEDIUM: 3,  # 3D fix (VO tracking valid per solution.md)
-        ConfidenceTier.LOW: 0,
-        ConfidenceTier.FAILED: 0,
-    }.get(confidence, 0)
-
-
-def _eskf_to_gps_input(
-    state: ESKFState,
-    origin: GPSPoint,
-    altitude_m: float = 0.0,
-) -> GPSInputMessage:
-    """Build a GPSInputMessage from ESKF state (MAV-02).
-
-    Args:
-        state:       Current ESKF nominal state.
-        origin:      WGS84 ENU reference origin set at mission start.
-        altitude_m:  Barometric altitude in metres MSL (from FC telemetry).
-    """
-    # ENU → WGS84
-    east, north = state.position[0], state.position[1]
-    cos_lat = math.cos(math.radians(origin.lat))
-    lat_wgs84 = origin.lat + north / 111_319.5
-    lon_wgs84 = origin.lon + east / (cos_lat * 111_319.5)
-
-    # Velocity: ENU → NED
-    vn = state.velocity[1]   # North = ENU[1]
-    ve = state.velocity[0]   # East  = ENU[0]
-    vd = -state.velocity[2]  # Down  = -Up
-
-    # Accuracy from covariance (position block = rows 0-2, cols 0-2)
-    cov_pos = state.covariance[:3, :3]
-    sigma_h = math.sqrt(max(0.0, cov_pos[0, 0] + cov_pos[1, 1]))
-    sigma_v = math.sqrt(max(0.0, cov_pos[2, 2]))
-    speed_sigma = math.sqrt(max(0.0, (state.covariance[3, 3] + state.covariance[4, 4]) / 2.0))
-
-    # Synthesised hdop/vdop (hdop ≈ σ_h / 5 maps to typical DOP scale)
-    hdop = max(0.1, sigma_h / 5.0)
-    vdop = max(0.1, sigma_v / 5.0)
-
-    fix_type = _confidence_to_fix_type(state.confidence)
-
-    now = state.timestamp if state.timestamp > 0 else time.time()
-    week, week_ms = _unix_to_gps_time(now)
-
-    return GPSInputMessage(
-        time_usec=int(now * 1_000_000),
-        time_week=week,
-        time_week_ms=week_ms,
-        fix_type=fix_type,
-        lat=int(lat_wgs84 * 1e7),
-        lon=int(lon_wgs84 * 1e7),
-        alt=altitude_m,
-        hdop=round(hdop, 2),
-        vdop=round(vdop, 2),
-        vn=round(vn, 4),
-        ve=round(ve, 4),
-        vd=round(vd, 4),
-        speed_accuracy=round(speed_sigma, 2),
-        horiz_accuracy=round(sigma_h, 2),
-        vert_accuracy=round(sigma_v, 2),
-        satellites_visible=10,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Mock MAVLink connection (dev/CI)
-# ---------------------------------------------------------------------------
-
-class MockMAVConnection:
-    """No-op MAVLink connection used when pymavlink is not installed."""
-
-    def __init__(self):
-        self._sent: list[dict] = []
-        self._rx_messages: list = []
-
-    def mav(self):
-        return self
-
-    def gps_input_send(self, *args, **kwargs) -> None:  # noqa: D102
-        self._sent.append({"type": "GPS_INPUT", "args": args, "kwargs": kwargs})
-
-    def named_value_float_send(self, *args, **kwargs) -> None:  # noqa: D102
-        self._sent.append({"type": "NAMED_VALUE_FLOAT", "args": args, "kwargs": kwargs})
-
-    def recv_match(self, type=None, blocking=False, timeout=0.1):  # noqa: D102
-        return None
-
-    def close(self) -> None:
-        pass
-
-
-# ---------------------------------------------------------------------------
-# MAVLinkBridge
-# ---------------------------------------------------------------------------
-
-class MAVLinkBridge:
-    """Full MAVLink I/O bridge.
-
-    Usage::
-
-        bridge = MAVLinkBridge(connection_string="serial:/dev/ttyTHS1:57600")
-        await bridge.start(origin_gps, eskf_instance)
-        # ... flight ...
-        await bridge.stop()
-    """
-
-    def __init__(
-        self,
-        connection_string: str = "udp:127.0.0.1:14550",
-        output_hz: float = 5.0,
-        telemetry_hz: float = 1.0,
-        max_consecutive_failures: int = 3,
-    ):
-        self.connection_string = connection_string
-        self.output_hz = output_hz
-        self.telemetry_hz = telemetry_hz
-        self.max_consecutive_failures = max_consecutive_failures
-
-        self._conn = None
-        self._origin: Optional[GPSPoint] = None
-        self._altitude_m: float = 0.0
-
-        # State shared between loops
-        self._last_state: Optional[ESKFState] = None
-        self._last_gps: Optional[GPSPoint] = None
-        self._consecutive_failures: int = 0
-        self._frames_since_sat: int = 0
-        self._drift_estimate_m: float = 0.0
-
-        # Callbacks
-        self._on_imu: Optional[Callable[[IMUMeasurement], None]] = None
-        self._on_reloc_request: Optional[Callable[[RelocalizationRequest], None]] = None
-
-        # asyncio tasks
-        self._tasks: list[asyncio.Task] = []
-        self._running = False
-
-        # Diagnostics
-        self._sent_count: int = 0
-        self._recv_imu_count: int = 0
-
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
-    def set_imu_callback(self, cb: Callable[[IMUMeasurement], None]) -> None:
-        """Register callback invoked for each received IMU packet (MAV-03)."""
-        self._on_imu = cb
-
-    def set_reloc_callback(self, cb: Callable[[RelocalizationRequest], None]) -> None:
-        """Register callback invoked when re-localisation is requested (MAV-04)."""
-        self._on_reloc_request = cb
-
-    def update_state(self, state: ESKFState, altitude_m: float = 0.0) -> None:
-        """Push a fresh ESKF state snapshot (called by processor per frame)."""
-        self._last_state = state
-        self._altitude_m = altitude_m
-        if state.confidence in (ConfidenceTier.HIGH, ConfidenceTier.MEDIUM):
-            # Position available
-            self._consecutive_failures = 0
-        else:
-            self._consecutive_failures += 1
-
-    def notify_satellite_correction(self) -> None:
-        """Reset frames_since_sat counter after a satellite match."""
-        self._frames_since_sat = 0
-
-    def update_drift_estimate(self, drift_m: float) -> None:
-        """Update running drift estimate (metres) for telemetry."""
-        self._drift_estimate_m = drift_m
-
-    async def start(self, origin: GPSPoint) -> None:
-        """Open the connection and launch background I/O coroutines."""
-        self._origin = origin
-        self._running = True
-        self._conn = self._open_connection()
-        self._tasks = [
-            asyncio.create_task(self._gps_output_loop(), name="mav_gps_output"),
-            asyncio.create_task(self._imu_receive_loop(), name="mav_imu_input"),
-            asyncio.create_task(self._telemetry_loop(), name="mav_telemetry"),
-        ]
-        logger.info("MAVLinkBridge started (conn=%s, %g Hz)", self.connection_string, self.output_hz)
-
-    async def stop(self) -> None:
-        """Cancel background tasks and close connection."""
-        self._running = False
-        for t in self._tasks:
-            t.cancel()
-        await asyncio.gather(*self._tasks, return_exceptions=True)
-        self._tasks.clear()
-        if self._conn:
-            self._conn.close()
-            self._conn = None
-        logger.info("MAVLinkBridge stopped. sent=%d imu_rx=%d",
-                    self._sent_count, self._recv_imu_count)
-
-    def build_gps_input(self) -> Optional[GPSInputMessage]:
-        """Build GPSInputMessage from current ESKF state (public, for testing)."""
-        if self._last_state is None or self._origin is None:
-            return None
-        return _eskf_to_gps_input(self._last_state, self._origin, self._altitude_m)
-
-    # ------------------------------------------------------------------
-    # MAV-01/02: GPS_INPUT output loop
-    # ------------------------------------------------------------------
-
-    async def _gps_output_loop(self) -> None:
-        """Send GPS_INPUT at output_hz.  MAV-01 / MAV-02."""
-        interval = 1.0 / self.output_hz
-        while self._running:
-            try:
-                msg = self.build_gps_input()
-                if msg is not None:
-                    self._send_gps_input(msg)
-                    self._sent_count += 1
-
-                    # MAV-04: check consecutive failures
-                    if self._consecutive_failures >= self.max_consecutive_failures:
-                        self._send_reloc_request()
-            except Exception as exc:
-                logger.warning("GPS output loop error: %s", exc)
-            await asyncio.sleep(interval)
-
-    def _send_gps_input(self, msg: GPSInputMessage) -> None:
-        if self._conn is None:
-            return
-        try:
-            if _PYMAVLINK_AVAILABLE and not isinstance(self._conn, MockMAVConnection):
-                self._conn.mav.gps_input_send(
-                    msg.time_usec,
-                    msg.gps_id,
-                    msg.ignore_flags,
-                    msg.time_week_ms,
-                    msg.time_week,
-                    msg.fix_type,
-                    msg.lat,
-                    msg.lon,
-                    msg.alt,
-                    msg.hdop,
-                    msg.vdop,
-                    msg.vn,
-                    msg.ve,
-                    msg.vd,
-                    msg.speed_accuracy,
-                    msg.horiz_accuracy,
-                    msg.vert_accuracy,
-                    msg.satellites_visible,
-                )
-            else:
-                # MockMAVConnection records the call
-                self._conn.gps_input_send(
-                    time_usec=msg.time_usec,
-                    fix_type=msg.fix_type,
-                    lat=msg.lat,
-                    lon=msg.lon,
-                )
-        except Exception as exc:
-            logger.error("Failed to send GPS_INPUT: %s", exc)
-
-    # ------------------------------------------------------------------
-    # MAV-03: IMU receive loop
-    # ------------------------------------------------------------------
-
-    async def _imu_receive_loop(self) -> None:
-        """Receive ATTITUDE/RAW_IMU and invoke ESKF callback.  MAV-03."""
-        while self._running:
-            try:
-                raw = self._recv_imu()
-                if raw is not None:
-                    self._recv_imu_count += 1
-                    if self._on_imu:
-                        self._on_imu(raw)
-            except Exception as exc:
-                logger.warning("IMU receive loop error: %s", exc)
-            await asyncio.sleep(0.01)  # poll at ~100 Hz; blocks throttled by recv_match timeout
-
-    def _recv_imu(self) -> Optional[IMUMeasurement]:
-        """Try to read one IMU packet from the MAVLink connection."""
-        if self._conn is None:
-            return None
-        if isinstance(self._conn, MockMAVConnection):
-            return None  # mock produces no IMU traffic
-
-        try:
-            msg = self._conn.recv_match(type=["RAW_IMU", "SCALED_IMU2"], blocking=False, timeout=0.01)
-            if msg is None:
-                return None
-            t = time.time()
-            # RAW_IMU fields (all in milli-g / milli-rad/s — convert to SI)
-            ax = getattr(msg, "xacc", 0) * 9.80665e-3   # milli-g → m/s²
-            ay = getattr(msg, "yacc", 0) * 9.80665e-3
-            az = getattr(msg, "zacc", 0) * 9.80665e-3
-            gx = getattr(msg, "xgyro", 0) * 1e-3        # milli-rad/s → rad/s
-            gy = getattr(msg, "ygyro", 0) * 1e-3
-            gz = getattr(msg, "zgyro", 0) * 1e-3
-            return IMUMeasurement(
-                accel=np.array([ax, ay, az]),
-                gyro=np.array([gx, gy, gz]),
-                timestamp=t,
-            )
-        except Exception as exc:
-            logger.debug("IMU recv error: %s", exc)
-            return None
-
-    # ------------------------------------------------------------------
-    # MAV-04: Re-localisation request
-    # ------------------------------------------------------------------
-
-    def _send_reloc_request(self) -> None:
-        """Send NAMED_VALUE_FLOAT re-localisation beacon (MAV-04)."""
-        req = self._build_reloc_request()
-        if self._on_reloc_request:
-            self._on_reloc_request(req)
-        if self._conn is None:
-            return
-        try:
-            t_boot_ms = int((time.time() % (2**32 / 1000)) * 1000)
-            for name, value in [
-                ("RELOC_LAT", float(req.last_lat or 0.0)),
-                ("RELOC_LON", float(req.last_lon or 0.0)),
-                ("RELOC_UNC", float(req.uncertainty_m)),
-            ]:
-                if _PYMAVLINK_AVAILABLE and not isinstance(self._conn, MockMAVConnection):
-                    self._conn.mav.named_value_float_send(
-                        t_boot_ms,
-                        name.encode()[:10],
-                        value,
-                    )
-                else:
-                    self._conn.named_value_float_send(time=t_boot_ms, name=name, value=value)
-            logger.warning("Re-localisation request sent (failures=%d)", self._consecutive_failures)
-        except Exception as exc:
-            logger.error("Failed to send reloc request: %s", exc)
-
-    def _build_reloc_request(self) -> RelocalizationRequest:
-        last_lat, last_lon = None, None
-        if self._last_state is not None and self._origin is not None:
-            east = self._last_state.position[0]
-            north = self._last_state.position[1]
-            cos_lat = math.cos(math.radians(self._origin.lat))
-            last_lat = self._origin.lat + north / 111_319.5
-            last_lon = self._origin.lon + east / (cos_lat * 111_319.5)
-            cov = self._last_state.covariance[:2, :2]
-            sigma_h = math.sqrt(max(0.0, (cov[0, 0] + cov[1, 1]) / 2.0))
-        else:
-            sigma_h = 500.0
-        return RelocalizationRequest(
-            last_lat=last_lat,
-            last_lon=last_lon,
-            uncertainty_m=max(sigma_h * 3.0, 50.0),
-            consecutive_failures=self._consecutive_failures,
-        )
-
-    # ------------------------------------------------------------------
-    # MAV-05: Telemetry loop
-    # ------------------------------------------------------------------
-
-    async def _telemetry_loop(self) -> None:
-        """Send confidence + drift at 1 Hz.  MAV-05."""
-        interval = 1.0 / self.telemetry_hz
-        while self._running:
-            try:
-                self._send_telemetry()
-                self._frames_since_sat += 1
-            except Exception as exc:
-                logger.warning("Telemetry loop error: %s", exc)
-            await asyncio.sleep(interval)
-
-    def _send_telemetry(self) -> None:
-        if self._last_state is None or self._conn is None:
-            return
-
-        fix_type = _confidence_to_fix_type(self._last_state.confidence)
-        confidence_score = {
-            ConfidenceTier.HIGH: 1.0,
-            ConfidenceTier.MEDIUM: 0.6,
-            ConfidenceTier.LOW: 0.2,
-            ConfidenceTier.FAILED: 0.0,
-        }.get(self._last_state.confidence, 0.0)
-
-        telemetry = TelemetryMessage(
-            confidence_score=confidence_score,
-            drift_estimate_m=self._drift_estimate_m,
-            fix_type=fix_type,
-            frames_since_sat=self._frames_since_sat,
-        )
-
-        t_boot_ms = int((time.time() % (2**32 / 1000)) * 1000)
-        for name, value in [
-            ("CONF_SCORE", telemetry.confidence_score),
-            ("DRIFT_M", telemetry.drift_estimate_m),
-        ]:
-            try:
-                if _PYMAVLINK_AVAILABLE and not isinstance(self._conn, MockMAVConnection):
-                    self._conn.mav.named_value_float_send(
-                        t_boot_ms,
-                        name.encode()[:10],
-                        float(value),
-                    )
-                else:
-                    self._conn.named_value_float_send(time=t_boot_ms, name=name, value=float(value))
-            except Exception as exc:
-                logger.debug("Telemetry send error: %s", exc)
-
-    # ------------------------------------------------------------------
-    # Connection factory
-    # ------------------------------------------------------------------
-
-    def _open_connection(self):
-        if _PYMAVLINK_AVAILABLE:
-            try:
-                conn = _mavutil.mavlink_connection(self.connection_string)
-                logger.info("MAVLink connection opened: %s", self.connection_string)
-                return conn
-            except Exception as exc:
-                logger.warning("Cannot open MAVLink connection (%s) — using mock", exc)
-        return MockMAVConnection()
+__all__ = [
+    "MAVLinkBridgeProtocol",
+    "MAVLinkBridge",
+    "MockMAVConnection",
+    "_PYMAVLINK_AVAILABLE",
+    "_unix_to_gps_time",
+    "_confidence_to_fix_type",
+    "_eskf_to_gps_input",
+]

src/gps_denied/core/metric.py

@@ -1,216 +1,10 @@
-"""Metric Refinement (Component F09).
+"""Legacy import path. Phase 1 shim — code lives in components/satellite_matcher/."""
+from gps_denied.components.satellite_matcher.protocol import (  # noqa: F401
+    MetricRefiner,
+    IMetricRefinement,
+)
+from gps_denied.components.satellite_matcher.metric_refinement import (  # noqa: F401
+    MetricRefinement,
+)
 
-SAT-03: GSD normalization — downsample camera frame to satellite resolution.
-SAT-04: RANSAC homography → WGS84 position; confidence = inlier_ratio.
-"""
-
-import logging
-from abc import ABC, abstractmethod
-from typing import List, Optional, Tuple
-
-import cv2
-import numpy as np
-
-from gps_denied.core.models import IModelManager
-from gps_denied.schemas import GPSPoint
-from gps_denied.schemas.metric import AlignmentResult, ChunkAlignmentResult, Sim3Transform
-from gps_denied.schemas.satellite import TileBounds
-
-logger = logging.getLogger(__name__)
-
-
-class IMetricRefinement(ABC):
-    @abstractmethod
-    def align_to_satellite(self, uav_image: np.ndarray, satellite_tile: np.ndarray, tile_bounds: TileBounds) -> Optional[AlignmentResult]:
-        pass
-
-    @abstractmethod
-    def compute_homography(self, uav_image: np.ndarray, satellite_tile: np.ndarray) -> Optional[np.ndarray]:
-        pass
-
-    @abstractmethod
-    def extract_gps_from_alignment(self, homography: np.ndarray, tile_bounds: TileBounds, image_center: Tuple[int, int]) -> GPSPoint:
-        pass
-
-    @abstractmethod
-    def compute_match_confidence(self, alignment: AlignmentResult) -> float:
-        pass
-
-    @abstractmethod
-    def align_chunk_to_satellite(self, chunk_images: List[np.ndarray], satellite_tile: np.ndarray, tile_bounds: TileBounds) -> Optional[ChunkAlignmentResult]:
-        pass
-
-    @abstractmethod
-    def match_chunk_homography(self, chunk_images: List[np.ndarray], satellite_tile: np.ndarray) -> Optional[np.ndarray]:
-        pass
-
-
-class MetricRefinement(IMetricRefinement):
-    """LiteSAM/XFeat-based alignment with GSD normalization.
-
-    SAT-03: normalize_gsd() downsamples UAV frame to match satellite GSD before matching.
-    SAT-04: confidence is computed as inlier_count / total_correspondences (inlier ratio).
-    """
-
-    def __init__(self, model_manager: IModelManager):
-        self.model_manager = model_manager
-
-    # ------------------------------------------------------------------
-    # SAT-03: GSD normalization
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def normalize_gsd(
-        uav_image: np.ndarray,
-        uav_gsd_mpp: float,
-        sat_gsd_mpp: float,
-    ) -> np.ndarray:
-        """Resize UAV frame to match satellite GSD (meters-per-pixel).
-
-        Args:
-            uav_image:    Raw UAV camera frame.
-            uav_gsd_mpp:  UAV GSD in m/px (e.g. 0.159 at 600 m altitude).
-            sat_gsd_mpp:  Satellite tile GSD in m/px (e.g. 0.6 at zoom 18).
-
-        Returns:
-            Resized image.  If already coarser than satellite, returned unchanged.
-        """
-        if uav_gsd_mpp <= 0 or sat_gsd_mpp <= 0:
-            return uav_image
-        scale = uav_gsd_mpp / sat_gsd_mpp
-        if scale >= 1.0:
-            return uav_image  # UAV already coarser, nothing to do
-        h, w = uav_image.shape[:2]
-        new_w = max(1, int(w * scale))
-        new_h = max(1, int(h * scale))
-        return cv2.resize(uav_image, (new_w, new_h), interpolation=cv2.INTER_AREA)
-
-    def compute_homography(self, uav_image: np.ndarray, satellite_tile: np.ndarray) -> Optional[np.ndarray]:
-        engine = self.model_manager.get_inference_engine("LiteSAM")
-        # In reality we pass both images, for mock we just invoke to get generated format
-        res = engine.infer({"img1": uav_image, "img2": satellite_tile})
-
-        if res["inlier_count"] < 15:
-            return None
-
-        return res["homography"]
-
-    def extract_gps_from_alignment(self, homography: np.ndarray, tile_bounds: TileBounds, image_center: Tuple[int, int]) -> GPSPoint:
-        # UAV image center
-        cx, cy = image_center
-        # Apply homography
-        pt = np.array([cx, cy, 1.0])
-        # transformed = H * pt
-        transformed = homography @ pt
-        transformed = transformed / transformed[2]
-
-        tx, ty = transformed[0], transformed[1]
-
-        # Approximate GPS mapping using bounds
-        # ty maps to latitude (ty=0 is North, ty=Height is South)
-        # tx maps to longitude (tx=0 is West, tx=Width is East)
-        # We assume standard 256x256 tiles for this mock calculation
-        tile_size = 256.0
-
-        lat_span = tile_bounds.nw.lat - tile_bounds.sw.lat
-        lon_span = tile_bounds.ne.lon - tile_bounds.nw.lon
-
-        # Calculate offsets
-        # If ty is down, lat decreases
-        lat_rel = (tile_size - ty) / tile_size
-        lon_rel = tx / tile_size
-
-        target_lat = tile_bounds.sw.lat + (lat_span * lat_rel)
-        target_lon = tile_bounds.nw.lon + (lon_span * lon_rel)
-
-        return GPSPoint(lat=target_lat, lon=target_lon)
-
-    def align_to_satellite(
-        self,
-        uav_image: np.ndarray,
-        satellite_tile: np.ndarray,
-        tile_bounds: TileBounds,
-        uav_gsd_mpp: float = 0.0,
-    ) -> Optional[AlignmentResult]:
-        """Align UAV frame to satellite tile.
-
-        Args:
-            uav_gsd_mpp: If > 0, the UAV frame is GSD-normalised to satellite
-                         resolution before matching (SAT-03).
-        """
-        # SAT-03: optional GSD normalization
-        sat_gsd = tile_bounds.gsd
-        if uav_gsd_mpp > 0 and sat_gsd > 0:
-            uav_image = self.normalize_gsd(uav_image, uav_gsd_mpp, sat_gsd)
-
-        engine = self.model_manager.get_inference_engine("LiteSAM")
-        res = engine.infer({"img1": uav_image, "img2": satellite_tile})
-
-        if res["inlier_count"] < 15:
-            return None
-
-        h, w = uav_image.shape[:2] if hasattr(uav_image, "shape") else (480, 640)
-        gps = self.extract_gps_from_alignment(res["homography"], tile_bounds, (w // 2, h // 2))
-
-        # SAT-04: confidence = inlier_ratio (not raw engine confidence)
-        total = res.get("total_correspondences", max(res["inlier_count"], 1))
-        inlier_ratio = res["inlier_count"] / max(total, 1)
-
-        align = AlignmentResult(
-            matched=True,
-            homography=res["homography"],
-            gps_center=gps,
-            confidence=inlier_ratio,
-            inlier_count=res["inlier_count"],
-            total_correspondences=total,
-            reprojection_error=res.get("reprojection_error", 1.0),
-        )
-        return align if self.compute_match_confidence(align) > 0.5 else None
-
-    def compute_match_confidence(self, alignment: AlignmentResult) -> float:
-        # Complex heuristic combining inliers, reprojection error
-        score = alignment.confidence
-        # Penalty for high reproj error
-        if alignment.reprojection_error > 2.0:
-            score -= 0.2
-        return max(0.0, min(1.0, score))
-
-    def match_chunk_homography(self, chunk_images: List[np.ndarray], satellite_tile: np.ndarray) -> Optional[np.ndarray]:
-        # Aggregate logic is complex, for mock we just use the first image's match
-        if not chunk_images:
-            return None
-        return self.compute_homography(chunk_images[0], satellite_tile)
-
-    def align_chunk_to_satellite(self, chunk_images: List[np.ndarray], satellite_tile: np.ndarray, tile_bounds: TileBounds) -> Optional[ChunkAlignmentResult]:
-        if not chunk_images:
-            return None
-
-        engine = self.model_manager.get_inference_engine("LiteSAM")
-        res = engine.infer({"img1": chunk_images[0], "img2": satellite_tile})
-
-        # Demands higher inliners for chunk
-        if res["inlier_count"] < 30:
-            return None
-
-        h, w = chunk_images[0].shape[:2] if hasattr(chunk_images[0], "shape") else (480, 640)
-        gps = self.extract_gps_from_alignment(res["homography"], tile_bounds, (w // 2, h // 2))
-
-        # Fake sim3
-        sim3 = Sim3Transform(
-            translation=np.array([10., 0., 0.]),
-            rotation=np.eye(3),
-            scale=1.0
-        )
-
-        chunk_align = ChunkAlignmentResult(
-            matched=True,
-            chunk_id="chunk1",
-            chunk_center_gps=gps,
-            rotation_angle=0.0,
-            confidence=res["confidence"],
-            inlier_count=res["inlier_count"],
-            transform=sim3,
-            reprojection_error=1.0
-        )
-
-        return chunk_align
+__all__ = ["MetricRefinement", "IMetricRefinement", "MetricRefiner"]

src/gps_denied/core/models.py

@@ -10,8 +10,7 @@ file is available, otherwise falls back to Mock.
 
 import logging
 import os
-from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, Protocol, runtime_checkable
 
 import numpy as np
 
@@ -31,26 +30,22 @@ def _is_jetson() -> bool:
     return os.path.exists("/sys/bus/platform/drivers/tegra-se-nvhost")
 
 
-class IModelManager(ABC):
-    @abstractmethod
+@runtime_checkable
+class IModelManager(Protocol):
     def load_model(self, model_name: str, model_format: str) -> bool:
-        pass
+        ...
 
-    @abstractmethod
     def get_inference_engine(self, model_name: str) -> InferenceEngine:
-        pass
+        ...
 
-    @abstractmethod
     def optimize_to_tensorrt(self, model_name: str, onnx_path: str) -> str:
-        pass
+        ...
 
-    @abstractmethod
     def fallback_to_onnx(self, model_name: str) -> bool:
-        pass
+        ...
 
-    @abstractmethod
     def warmup_model(self, model_name: str) -> bool:
-        pass
+        ...
 
 
 class MockInferenceEngine(InferenceEngine):

src/gps_denied/core/pipeline.py

@@ -1,227 +1,6 @@
-"""Image Input Pipeline (Component F05)."""
-
-import asyncio
-import os
-import re
-from datetime import datetime, timezone
-
-import cv2
-import numpy as np
-
-from gps_denied.schemas.image import (
-    ImageBatch,
-    ImageData,
-    ImageMetadata,
-    ProcessedBatch,
-    ProcessingStatus,
-    ValidationResult,
+"""Legacy import path. Phase 1 shim — code lives in pipeline/image_input.py."""
+from gps_denied.pipeline.image_input import (  # noqa: F401
+    ImageInputPipeline,
+    QueueFullError,
+    ValidationError,
 )
-
-
-class QueueFullError(Exception):
-    pass
-
-class ValidationError(Exception):
-    pass
-
-
-class ImageInputPipeline:
-    """Manages ingestion, disk storage, and queuing of UAV image batches."""
-
-    def __init__(self, storage_dir: str = "image_storage", max_queue_size: int = 50):
-        self.storage_dir = storage_dir
-        # flight_id -> asyncio.Queue of ImageBatch
-        self._queues: dict[str, asyncio.Queue] = {}
-        self.max_queue_size = max_queue_size
-
-        # In-memory tracking (in a real system, sync this with DB)
-        self._status: dict[str, dict] = {}
-        # Exact sequence → filename mapping (VO-05: no substring collision)
-        self._sequence_map: dict[str, dict[int, str]] = {}
-
-    def _get_queue(self, flight_id: str) -> asyncio.Queue:
-        if flight_id not in self._queues:
-            self._queues[flight_id] = asyncio.Queue(maxsize=self.max_queue_size)
-        return self._queues[flight_id]
-
-    def _init_status(self, flight_id: str):
-        if flight_id not in self._status:
-            self._status[flight_id] = {
-                "total_images": 0,
-                "processed_images": 0,
-                "current_sequence": 1,
-            }
-
-    def validate_batch(self, batch: ImageBatch) -> ValidationResult:
-        """Validates batch integrity and sequence continuity."""
-        errors = []
-
-        num_images = len(batch.images)
-        if num_images < 1:
-            errors.append("Batch is empty")
-        elif num_images > 100:
-            errors.append("Batch too large")
-
-        if len(batch.filenames) != num_images:
-            errors.append("Mismatch between filenames and images count")
-
-        # Naming convention ADxxxxxx.jpg or similar
-        pattern = re.compile(r"^[A-Za-z0-9_-]+\.(jpg|jpeg|png)$", re.IGNORECASE)
-        for fn in batch.filenames:
-            if not pattern.match(fn):
-                errors.append(f"Invalid filename: {fn}")
-                break
-
-        if batch.start_sequence > batch.end_sequence:
-            errors.append("Start sequence greater than end sequence")
-
-        return ValidationResult(valid=len(errors) == 0, errors=errors)
-
-    def queue_batch(self, flight_id: str, batch: ImageBatch) -> bool:
-        """Queues a batch of images for processing."""
-        val = self.validate_batch(batch)
-        if not val.valid:
-            raise ValidationError(f"Batch validation failed: {val.errors}")
-
-        q = self._get_queue(flight_id)
-        if q.full():
-            raise QueueFullError(f"Queue for flight {flight_id} is full")
-
-        q.put_nowait(batch)
-
-        self._init_status(flight_id)
-        self._status[flight_id]["total_images"] += len(batch.images)
-
-        return True
-
-    async def process_next_batch(self, flight_id: str) -> ProcessedBatch | None:
-        """Dequeues and processing the next batch."""
-        q = self._get_queue(flight_id)
-        if q.empty():
-            return None
-
-        batch: ImageBatch = await q.get()
-
-        processed_images = []
-        for i, raw_bytes in enumerate(batch.images):
-            # Decode
-            nparr = np.frombuffer(raw_bytes, np.uint8)
-            img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
-
-            if img is None:
-                continue  # skip corrupted
-
-            seq = batch.start_sequence + i
-            fn = batch.filenames[i]
-
-            h, w = img.shape[:2]
-            meta = ImageMetadata(
-                sequence=seq,
-                filename=fn,
-                dimensions=(w, h),
-                file_size=len(raw_bytes),
-                timestamp=datetime.now(timezone.utc),
-            )
-
-            img_data = ImageData(
-                flight_id=flight_id,
-                sequence=seq,
-                filename=fn,
-                image=img,
-                metadata=meta
-            )
-            processed_images.append(img_data)
-            # VO-05: record exact sequence→filename mapping
-            self._sequence_map.setdefault(flight_id, {})[seq] = fn
-
-        # Store to disk
-        self.store_images(flight_id, processed_images)
-
-        self._status[flight_id]["processed_images"] += len(processed_images)
-        q.task_done()
-
-        return ProcessedBatch(
-            images=processed_images,
-            batch_id=f"batch_{batch.batch_number}",
-            start_sequence=batch.start_sequence,
-            end_sequence=batch.end_sequence
-        )
-
-    def store_images(self, flight_id: str, images: list[ImageData]) -> bool:
-        """Persists images to disk."""
-        flight_dir = os.path.join(self.storage_dir, flight_id)
-        os.makedirs(flight_dir, exist_ok=True)
-
-        for img in images:
-            path = os.path.join(flight_dir, img.filename)
-            cv2.imwrite(path, img.image)
-
-        return True
-
-    def get_next_image(self, flight_id: str) -> ImageData | None:
-        """Gets the next image in sequence for processing."""
-        self._init_status(flight_id)
-        seq = self._status[flight_id]["current_sequence"]
-
-        img = self.get_image_by_sequence(flight_id, seq)
-        if img:
-            self._status[flight_id]["current_sequence"] += 1
-
-        return img
-
-    def get_image_by_sequence(self, flight_id: str, sequence: int) -> ImageData | None:
-        """Retrieves a specific image by sequence number (exact match — VO-05)."""
-        flight_dir = os.path.join(self.storage_dir, flight_id)
-        if not os.path.exists(flight_dir):
-            return None
-
-        # Prefer the exact mapping built during process_next_batch
-        fn = self._sequence_map.get(flight_id, {}).get(sequence)
-        if fn:
-            path = os.path.join(flight_dir, fn)
-            img = cv2.imread(path)
-            if img is not None:
-                h, w = img.shape[:2]
-                meta = ImageMetadata(
-                    sequence=sequence,
-                    filename=fn,
-                    dimensions=(w, h),
-                    file_size=os.path.getsize(path),
-                    timestamp=datetime.now(timezone.utc),
-                )
-                return ImageData(flight_id, sequence, fn, img, meta)
-
-        # Fallback: scan directory for exact filename patterns
-        # (handles images stored before this process started)
-        for fn in os.listdir(flight_dir):
-            base, _ = os.path.splitext(fn)
-            # Accept only if the base name ends with exactly the padded sequence number
-            if base.endswith(f"{sequence:06d}") or base == str(sequence):
-                path = os.path.join(flight_dir, fn)
-                img = cv2.imread(path)
-                if img is not None:
-                    h, w = img.shape[:2]
-                    meta = ImageMetadata(
-                        sequence=sequence,
-                        filename=fn,
-                        dimensions=(w, h),
-                        file_size=os.path.getsize(path),
-                        timestamp=datetime.now(timezone.utc),
-                    )
-                    return ImageData(flight_id, sequence, fn, img, meta)
-
-        return None
-
-    def get_processing_status(self, flight_id: str) -> ProcessingStatus:
-        self._init_status(flight_id)
-        s = self._status[flight_id]
-        q = self._get_queue(flight_id)
-
-        return ProcessingStatus(
-            flight_id=flight_id,
-            total_images=s["total_images"],
-            processed_images=s["processed_images"],
-            current_sequence=s["current_sequence"],
-            queued_batches=q.qsize(),
-            processing_rate=0.0  # mock
-        )

src/gps_denied/core/processor.py

@@ -1,599 +1,6 @@
-"""Core Flight Processor — Full Processing Pipeline (Stage 10).
-
-Orchestrates: ImageInputPipeline → VO → MetricRefinement → FactorGraph → SSE.
-State Machine: NORMAL → LOST → RECOVERY → NORMAL.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import time
-from enum import Enum
-from typing import Optional
-
-import numpy as np
-
-from gps_denied.core.eskf import ESKF
-from gps_denied.core.pipeline import ImageInputPipeline
-from gps_denied.core.results import ResultManager
-from gps_denied.core.sse import SSEEventStreamer
-from gps_denied.db.repository import FlightRepository
-from gps_denied.schemas import CameraParameters, GPSPoint
-from gps_denied.schemas.flight import (
-    BatchMetadata,
-    BatchResponse,
-    BatchUpdateResponse,
-    DeleteResponse,
-    FlightCreateRequest,
-    FlightDetailResponse,
-    FlightResponse,
-    FlightStatusResponse,
-    ObjectGPSResponse,
-    UpdateResponse,
-    UserFixRequest,
-    UserFixResponse,
-    Waypoint,
+"""Legacy import path. Phase 1 shim — code lives in pipeline/orchestrator.py."""
+from gps_denied.pipeline.orchestrator import (  # noqa: F401
+    FlightProcessor,
+    TrackingState,
+    FrameResult,
 )
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# State Machine
-# ---------------------------------------------------------------------------
-class TrackingState(str, Enum):
-    """Processing state for a flight."""
-    NORMAL = "normal"
-    LOST = "lost"
-    RECOVERY = "recovery"
-
-
-class FrameResult:
-    """Intermediate result of processing a single frame."""
-
-    def __init__(self, frame_id: int):
-        self.frame_id = frame_id
-        self.gps: Optional[GPSPoint] = None
-        self.confidence: float = 0.0
-        self.tracking_state: TrackingState = TrackingState.NORMAL
-        self.vo_success: bool = False
-        self.alignment_success: bool = False
-
-
-# ---------------------------------------------------------------------------
-# FlightProcessor
-# ---------------------------------------------------------------------------
-class FlightProcessor:
-    """Manages business logic, background processing, and frame orchestration."""
-
-    def __init__(
-        self,
-        repository: FlightRepository,
-        streamer: SSEEventStreamer,
-        eskf_config=None,
-    ) -> None:
-        self.repository = repository
-        self.streamer = streamer
-        self.result_manager = ResultManager(repository, streamer)
-        self.pipeline = ImageInputPipeline(storage_dir=".image_storage", max_queue_size=50)
-        self._eskf_config = eskf_config  # ESKFConfig or None → default
-
-        # Per-flight processing state
-        self._flight_states: dict[str, TrackingState] = {}
-        self._prev_images: dict[str, np.ndarray] = {}  # previous frame cache
-        self._flight_cameras: dict[str, CameraParameters] = {}  # per-flight camera
-        self._altitudes: dict[str, float] = {}          # per-flight altitude (m)
-        self._failure_counts: dict[str, int] = {}       # per-flight consecutive failure counter
-
-        # Per-flight ESKF instances (PIPE-01/07)
-        self._eskf: dict[str, ESKF] = {}
-
-        # Lazy-initialised component references (set via `attach_components`)
-        self._vo = None           # ISequentialVisualOdometry
-        self._gpr = None          # IGlobalPlaceRecognition
-        self._metric = None       # IMetricRefinement
-        self._graph = None        # IFactorGraphOptimizer
-        self._recovery = None     # IFailureRecoveryCoordinator
-        self._chunk_mgr = None    # IRouteChunkManager
-        self._rotation = None     # ImageRotationManager
-        self._satellite = None    # SatelliteDataManager (PIPE-02)
-        self._coord = None        # CoordinateTransformer (PIPE-02/06)
-        self._mavlink = None      # MAVLinkBridge (PIPE-07)
-
-    # ------ Dependency injection for core components ---------
-    def attach_components(
-        self,
-        vo=None,
-        gpr=None,
-        metric=None,
-        graph=None,
-        recovery=None,
-        chunk_mgr=None,
-        rotation=None,
-        satellite=None,
-        coord=None,
-        mavlink=None,
-    ):
-        """Attach pipeline components after construction (avoids circular deps)."""
-        self._vo = vo
-        self._gpr = gpr
-        self._metric = metric
-        self._graph = graph
-        self._recovery = recovery
-        self._chunk_mgr = chunk_mgr
-        self._rotation = rotation
-        self._satellite = satellite   # PIPE-02: SatelliteDataManager
-        self._coord = coord           # PIPE-02/06: CoordinateTransformer
-        self._mavlink = mavlink       # PIPE-07: MAVLinkBridge
-
-    # ------ ESKF lifecycle helpers ----------------------------
-    def _init_eskf_for_flight(
-        self, flight_id: str, start_gps: GPSPoint, altitude: float
-    ) -> None:
-        """Create and initialize a per-flight ESKF instance."""
-        if flight_id in self._eskf:
-            return
-        eskf = ESKF(config=self._eskf_config)
-        if self._coord:
-            try:
-                e, n, _ = self._coord.gps_to_enu(flight_id, start_gps)
-                eskf.initialize(np.array([e, n, altitude]), time.time())
-            except Exception:
-                eskf.initialize(np.zeros(3), time.time())
-        else:
-            eskf.initialize(np.zeros(3), time.time())
-        self._eskf[flight_id] = eskf
-
-    def _eskf_to_gps(self, flight_id: str, eskf: ESKF) -> Optional[GPSPoint]:
-        """Convert current ESKF ENU position to WGS84 GPS."""
-        if not eskf.initialized or self._coord is None:
-            return None
-        try:
-            pos = eskf.position
-            return self._coord.enu_to_gps(flight_id, (float(pos[0]), float(pos[1]), float(pos[2])))
-        except Exception:
-            return None
-
-    # =========================================================
-    # process_frame — central orchestration
-    # =========================================================
-    async def process_frame(
-        self,
-        flight_id: str,
-        frame_id: int,
-        image: np.ndarray,
-    ) -> FrameResult:
-        """
-        Process a single UAV frame through the full pipeline.
-
-        State transitions:
-            NORMAL  — VO succeeds → ESKF VO update, attempt satellite fix
-            LOST    — VO failed → create new chunk, enter RECOVERY
-            RECOVERY— try GPR + MetricRefinement → if anchored, merge & return to NORMAL
-
-        PIPE-01: VO result → eskf.update_vo → satellite match → eskf.update_satellite → MAVLink GPS_INPUT
-        PIPE-02: SatelliteDataManager + CoordinateTransformer wired for tile selection
-        PIPE-04: Consecutive failure counter wired to FailureRecoveryCoordinator
-        PIPE-05: ImageRotationManager initialised on first frame
-        PIPE-07: ESKF confidence → MAVLink fix_type via bridge.update_state
-        """
-        result = FrameResult(frame_id)
-        state = self._flight_states.get(flight_id, TrackingState.NORMAL)
-        eskf = self._eskf.get(flight_id)
-
-        _default_cam = CameraParameters(
-            focal_length=4.5, sensor_width=6.17, sensor_height=4.55,
-            resolution_width=640, resolution_height=480,
-        )
-
-        # ---- PIPE-05: Initialise heading tracking on first frame ----
-        if self._rotation and frame_id == 0:
-            self._rotation.requires_rotation_sweep(flight_id)  # seeds HeadingHistory
-
-        # ---- 1. Visual Odometry (frame-to-frame) ----
-        vo_ok = False
-        if self._vo and flight_id in self._prev_images:
-            try:
-                cam = self._flight_cameras.get(flight_id, _default_cam)
-                rel_pose = self._vo.compute_relative_pose(
-                    self._prev_images[flight_id], image, cam
-                )
-                if rel_pose and rel_pose.tracking_good:
-                    vo_ok = True
-                    result.vo_success = True
-
-                    if self._graph:
-                        self._graph.add_relative_factor(
-                            flight_id, frame_id - 1, frame_id, rel_pose, np.eye(6)
-                        )
-
-                    # PIPE-01: Feed VO relative displacement into ESKF
-                    if eskf and eskf.initialized:
-                        now = time.time()
-                        dt_vo = max(0.01, now - (eskf.last_timestamp or now))
-                        eskf.update_vo(rel_pose.translation, dt_vo)
-            except Exception as exc:
-                logger.warning("VO failed for frame %d: %s", frame_id, exc)
-
-        # Store current image for next frame
-        self._prev_images[flight_id] = image
-
-        # ---- PIPE-04: Consecutive failure counter ----
-        if not vo_ok and frame_id > 0:
-            self._failure_counts[flight_id] = self._failure_counts.get(flight_id, 0) + 1
-        else:
-            self._failure_counts[flight_id] = 0
-
-        # ---- 2. State Machine transitions ----
-        if state == TrackingState.NORMAL:
-            if not vo_ok and frame_id > 0:
-                state = TrackingState.LOST
-                logger.info("Flight %s → LOST at frame %d", flight_id, frame_id)
-                if self._recovery:
-                    self._recovery.handle_tracking_lost(flight_id, frame_id)
-
-        if state == TrackingState.LOST:
-            state = TrackingState.RECOVERY
-
-        if state == TrackingState.RECOVERY:
-            recovered = False
-            if self._recovery and self._chunk_mgr:
-                active_chunk = self._chunk_mgr.get_active_chunk(flight_id)
-                if active_chunk:
-                    recovered = self._recovery.process_chunk_recovery(
-                        flight_id, active_chunk.chunk_id, [image]
-                    )
-            if recovered:
-                state = TrackingState.NORMAL
-                result.alignment_success = True
-                # PIPE-04: Reset failure count on successful recovery
-                self._failure_counts[flight_id] = 0
-                logger.info("Flight %s recovered → NORMAL at frame %d", flight_id, frame_id)
-
-        # ---- 3. Satellite position fix (PIPE-01/02) ----
-        if state == TrackingState.NORMAL and self._metric:
-            sat_tile: Optional[np.ndarray] = None
-            tile_bounds = None
-
-            # PIPE-02: Prefer real SatelliteDataManager tiles (ESKF ±3σ selection)
-            if self._satellite and eskf and eskf.initialized:
-                gps_est = self._eskf_to_gps(flight_id, eskf)
-                if gps_est:
-                    cov = eskf.covariance
-                    sigma_h = float(
-                        np.sqrt(np.trace(cov[0:3, 0:3]) / 3.0)
-                    ) if cov is not None else 30.0
-                    sigma_h = max(sigma_h, 5.0)
-                    try:
-                        tile_result = await asyncio.get_event_loop().run_in_executor(
-                            None,
-                            self._satellite.fetch_tiles_for_position,
-                            gps_est, sigma_h, 18,
-                        )
-                        if tile_result:
-                            sat_tile, tile_bounds = tile_result
-                    except Exception as exc:
-                        logger.debug("Satellite tile fetch failed: %s", exc)
-
-            # Fallback: GPR candidate tile (mock image, real bounds)
-            if sat_tile is None and self._gpr:
-                try:
-                    candidates = self._gpr.retrieve_candidate_tiles(image, top_k=1)
-                    if candidates:
-                        sat_tile = np.zeros((256, 256, 3), dtype=np.uint8)
-                        tile_bounds = candidates[0].bounds
-                except Exception as exc:
-                    logger.debug("GPR tile fallback failed: %s", exc)
-
-            if sat_tile is not None and tile_bounds is not None:
-                try:
-                    align = self._metric.align_to_satellite(image, sat_tile, tile_bounds)
-                    if align and align.matched:
-                        result.gps = align.gps_center
-                        result.confidence = align.confidence
-                        result.alignment_success = True
-
-                        if self._graph:
-                            self._graph.add_absolute_factor(
-                                flight_id, frame_id,
-                                align.gps_center, np.eye(6),
-                                is_user_anchor=False,
-                            )
-
-                        # PIPE-01: ESKF satellite update — noise from RANSAC confidence
-                        if eskf and eskf.initialized and self._coord:
-                            try:
-                                e, n, _ = self._coord.gps_to_enu(flight_id, align.gps_center)
-                                alt = self._altitudes.get(flight_id, 100.0)
-                                pos_enu = np.array([e, n, alt])
-                                noise_m = 5.0 + 15.0 * (1.0 - float(align.confidence))
-                                eskf.update_satellite(pos_enu, noise_m)
-                            except Exception as exc:
-                                logger.debug("ESKF satellite update failed: %s", exc)
-                except Exception as exc:
-                    logger.warning("Metric alignment failed at frame %d: %s", frame_id, exc)
-
-        # ---- 4. Graph optimization (incremental) ----
-        if self._graph:
-            opt_result = self._graph.optimize(flight_id, iterations=5)
-            logger.debug(
-                "Optimization: converged=%s, error=%.4f",
-                opt_result.converged, opt_result.final_error,
-            )
-
-        # ---- PIPE-07: Push ESKF state → MAVLink GPS_INPUT ----
-        if self._mavlink and eskf and eskf.initialized:
-            try:
-                eskf_state = eskf.get_state()
-                alt = self._altitudes.get(flight_id, 100.0)
-                self._mavlink.update_state(eskf_state, altitude_m=alt)
-            except Exception as exc:
-                logger.debug("MAVLink state push failed: %s", exc)
-
-        # ---- 5. Publish via SSE ----
-        result.tracking_state = state
-        self._flight_states[flight_id] = state
-        await self._publish_frame_result(flight_id, result)
-        return result
-
-    async def _publish_frame_result(self, flight_id: str, result: FrameResult):
-        """Emit SSE event for processed frame."""
-        event_data = {
-            "frame_id": result.frame_id,
-            "tracking_state": result.tracking_state.value,
-            "vo_success": result.vo_success,
-            "alignment_success": result.alignment_success,
-            "confidence": result.confidence,
-        }
-        if result.gps:
-            event_data["lat"] = result.gps.lat
-            event_data["lon"] = result.gps.lon
-
-        await self.streamer.push_event(
-            flight_id, event_type="frame_result", data=event_data
-        )
-
-    # =========================================================
-    # Existing CRUD / REST helpers (unchanged from Stage 3-4)
-    # =========================================================
-    async def create_flight(self, req: FlightCreateRequest) -> FlightResponse:
-        flight = await self.repository.insert_flight(
-            name=req.name,
-            description=req.description,
-            start_lat=req.start_gps.lat,
-            start_lon=req.start_gps.lon,
-            altitude=req.altitude,
-            camera_params=req.camera_params.model_dump(),
-        )
-        # P0#2: Store camera params for process_frame VO calls
-        self._flight_cameras[flight.id] = req.camera_params
-
-        for poly in req.geofences.polygons:
-            await self.repository.insert_geofence(
-                flight.id,
-                nw_lat=poly.north_west.lat,
-                nw_lon=poly.north_west.lon,
-                se_lat=poly.south_east.lat,
-                se_lon=poly.south_east.lon,
-            )
-        for w in req.rough_waypoints:
-            await self.repository.insert_waypoint(flight.id, lat=w.lat, lon=w.lon)
-
-        # Store per-flight altitude for ESKF/pixel projection
-        self._altitudes[flight.id] = req.altitude or 100.0
-
-        # PIPE-02: Set ENU origin and initialise ESKF for this flight
-        if self._coord:
-            self._coord.set_enu_origin(flight.id, req.start_gps)
-        self._init_eskf_for_flight(flight.id, req.start_gps, req.altitude or 100.0)
-
-        # Start MAVLink bridge for this flight (origin required for GPS_INPUT)
-        if self._mavlink and not self._mavlink._running:
-            try:
-                asyncio.create_task(self._mavlink.start(req.start_gps))
-            except Exception as exc:
-                logger.warning("MAVLink bridge start failed: %s", exc)
-
-        return FlightResponse(
-            flight_id=flight.id,
-            status="prefetching",
-            message="Flight created and prefetching started.",
-            created_at=flight.created_at,
-        )
-
-    async def get_flight(self, flight_id: str) -> FlightDetailResponse | None:
-        flight = await self.repository.get_flight(flight_id)
-        if not flight:
-            return None
-        wps = await self.repository.get_waypoints(flight_id)
-        state = await self.repository.load_flight_state(flight_id)
-
-        waypoints = [
-            Waypoint(
-                id=w.id,
-                lat=w.lat,
-                lon=w.lon,
-                altitude=w.altitude,
-                confidence=w.confidence,
-                timestamp=w.timestamp,
-                refined=w.refined,
-            )
-            for w in wps
-        ]
-
-        status = state.status if state else "unknown"
-        frames_processed = state.frames_processed if state else 0
-        frames_total = state.frames_total if state else 0
-
-        from gps_denied.schemas import Geofences
-
-        return FlightDetailResponse(
-            flight_id=flight.id,
-            name=flight.name,
-            description=flight.description,
-            start_gps=GPSPoint(lat=flight.start_lat, lon=flight.start_lon),
-            waypoints=waypoints,
-            geofences=Geofences(polygons=[]),
-            camera_params=flight.camera_params,
-            altitude=flight.altitude,
-            status=status,
-            frames_processed=frames_processed,
-            frames_total=frames_total,
-            created_at=flight.created_at,
-            updated_at=flight.updated_at,
-        )
-
-    async def delete_flight(self, flight_id: str) -> DeleteResponse:
-        deleted = await self.repository.delete_flight(flight_id)
-        # P0#1: Cleanup in-memory state to prevent memory leaks
-        self._cleanup_flight(flight_id)
-        return DeleteResponse(deleted=deleted, flight_id=flight_id)
-
-    def _cleanup_flight(self, flight_id: str) -> None:
-        """Remove all in-memory state for a flight (prevents memory leaks)."""
-        self._prev_images.pop(flight_id, None)
-        self._flight_states.pop(flight_id, None)
-        self._flight_cameras.pop(flight_id, None)
-        self._altitudes.pop(flight_id, None)
-        self._failure_counts.pop(flight_id, None)
-        self._eskf.pop(flight_id, None)
-        if self._graph:
-            self._graph.delete_flight_graph(flight_id)
-
-    async def update_waypoint(
-        self, flight_id: str, waypoint_id: str, waypoint: Waypoint
-    ) -> UpdateResponse:
-        ok = await self.repository.update_waypoint(
-            flight_id,
-            waypoint_id,
-            lat=waypoint.lat,
-            lon=waypoint.lon,
-            altitude=waypoint.altitude,
-            confidence=waypoint.confidence,
-            refined=waypoint.refined,
-        )
-        return UpdateResponse(updated=ok, waypoint_id=waypoint_id)
-
-    async def batch_update_waypoints(
-        self, flight_id: str, waypoints: list[Waypoint]
-    ) -> BatchUpdateResponse:
-        failed = []
-        updated = 0
-        for wp in waypoints:
-            ok = await self.repository.update_waypoint(
-                flight_id,
-                wp.id,
-                lat=wp.lat,
-                lon=wp.lon,
-                altitude=wp.altitude,
-                confidence=wp.confidence,
-                refined=wp.refined,
-            )
-            if ok:
-                updated += 1
-            else:
-                failed.append(wp.id)
-        return BatchUpdateResponse(
-            success=(len(failed) == 0), updated_count=updated, failed_ids=failed
-        )
-
-    async def queue_images(
-        self, flight_id: str, metadata: BatchMetadata, file_count: int
-    ) -> BatchResponse:
-        state = await self.repository.load_flight_state(flight_id)
-        if state:
-            total = state.frames_total + file_count
-            await self.repository.save_flight_state(
-                flight_id, frames_total=total, status="processing"
-            )
-
-        next_seq = metadata.end_sequence + 1
-        seqs = list(range(metadata.start_sequence, metadata.end_sequence + 1))
-        return BatchResponse(
-            accepted=True,
-            sequences=seqs,
-            next_expected=next_seq,
-            message=f"Queued {file_count} images.",
-        )
-
-    async def handle_user_fix(
-        self, flight_id: str, req: UserFixRequest
-    ) -> UserFixResponse:
-        await self.repository.save_flight_state(
-            flight_id, blocked=False, status="processing"
-        )
-
-        # Inject operator position into ESKF with high uncertainty (500m)
-        eskf = self._eskf.get(flight_id)
-        if eskf and eskf.initialized and self._coord:
-            try:
-                e, n, _ = self._coord.gps_to_enu(flight_id, req.satellite_gps)
-                alt = self._altitudes.get(flight_id, 100.0)
-                eskf.update_satellite(np.array([e, n, alt]), noise_meters=500.0)
-                self._failure_counts[flight_id] = 0
-                logger.info("User fix applied for %s: %s", flight_id, req.satellite_gps)
-            except Exception as exc:
-                logger.warning("User fix ESKF injection failed: %s", exc)
-
-        return UserFixResponse(
-            accepted=True, processing_resumed=True, message="Fix applied."
-        )
-
-    async def get_flight_status(self, flight_id: str) -> FlightStatusResponse | None:
-        state = await self.repository.load_flight_state(flight_id)
-        if not state:
-            return None
-        return FlightStatusResponse(
-            status=state.status,
-            frames_processed=state.frames_processed,
-            frames_total=state.frames_total,
-            current_frame=state.current_frame,
-            current_heading=None,
-            blocked=state.blocked,
-            search_grid_size=state.search_grid_size,
-            created_at=state.created_at,
-            updated_at=state.updated_at,
-        )
-
-    async def convert_object_to_gps(
-        self, flight_id: str, frame_id: int, pixel: tuple[float, float]
-    ) -> ObjectGPSResponse:
-        # PIPE-06: Use real CoordinateTransformer + ESKF pose for ray-ground projection
-        gps: Optional[GPSPoint] = None
-        eskf = self._eskf.get(flight_id)
-        if self._coord and eskf and eskf.initialized:
-            pos = eskf.position
-            quat = eskf.quaternion
-            cam = self._flight_cameras.get(flight_id, CameraParameters(
-                focal_length=4.5, sensor_width=6.17, sensor_height=4.55,
-                resolution_width=640, resolution_height=480,
-            ))
-            alt = self._altitudes.get(flight_id, 100.0)
-            try:
-                gps = self._coord.pixel_to_gps(
-                    flight_id,
-                    pixel,
-                    frame_pose={"position": pos},
-                    camera_params=cam,
-                    altitude=float(alt),
-                    quaternion=quat,
-                )
-            except Exception as exc:
-                logger.debug("pixel_to_gps failed: %s", exc)
-
-        # Fallback: return ESKF position projected to ground (no pixel shift)
-        if gps is None and eskf:
-            gps = self._eskf_to_gps(flight_id, eskf)
-
-        return ObjectGPSResponse(
-            gps=gps or GPSPoint(lat=0.0, lon=0.0),
-            accuracy_meters=5.0,
-            frame_id=frame_id,
-            pixel=pixel,
-        )
-
-    async def stream_events(self, flight_id: str, client_id: str):
-        """Async generator for SSE stream."""
-        async for event in self.streamer.stream_generator(flight_id, client_id):
-            yield event

src/gps_denied/core/recovery.py

@@ -1,8 +1,7 @@
 """Failure Recovery Coordinator (Component F11)."""
 
 import logging
-from abc import ABC, abstractmethod
-from typing import List
+from typing import List, Protocol, runtime_checkable
 
 import numpy as np
 
@@ -14,14 +13,13 @@ from gps_denied.schemas.chunk import ChunkStatus
 logger = logging.getLogger(__name__)
 
 
-class IFailureRecoveryCoordinator(ABC):
-    @abstractmethod
+@runtime_checkable
+class IFailureRecoveryCoordinator(Protocol):
     def handle_tracking_lost(self, flight_id: str, current_frame_id: int) -> bool:
-        pass
+        ...
 
-    @abstractmethod
     def process_chunk_recovery(self, flight_id: str, chunk_id: str, images: List[np.ndarray]) -> bool:
-        pass
+        ...
 
 
 class FailureRecoveryCoordinator(IFailureRecoveryCoordinator):

src/gps_denied/core/results.py

@@ -1,73 +1,4 @@
-"""Result Manager (Component F14)."""
-
-from __future__ import annotations
-
-from datetime import datetime
-
-from gps_denied.core.sse import SSEEventStreamer
-from gps_denied.db.repository import FlightRepository
-from gps_denied.schemas import GPSPoint
-from gps_denied.schemas.events import FrameProcessedEvent
-
-
-class ResultManager:
-    """Result consistency and publishing."""
-
-    def __init__(self, repo: FlightRepository, sse: SSEEventStreamer) -> None:
-        self.repo = repo
-        self.sse = sse
-
-    async def update_frame_result(
-        self,
-        flight_id: str,
-        frame_id: int,
-        gps_lat: float,
-        gps_lon: float,
-        altitude: float,
-        heading: float,
-        confidence: float,
-        timestamp: datetime,
-        refined: bool = False,
-    ) -> bool:
-        """Atomic DB update + SSE event publish."""
-
-        # 1. Update DB (in the repository these are auto-committing via flush,
-        # but normally F03 would wrap in a single transaction).
-        await self.repo.save_frame_result(
-            flight_id,
-            frame_id=frame_id,
-            gps_lat=gps_lat,
-            gps_lon=gps_lon,
-            altitude=altitude,
-            heading=heading,
-            confidence=confidence,
-            refined=refined,
-        )
-
-        # Wait, the spec also wants Waypoints to be updated.
-        # But image frames != waypoints. Waypoints are the planned route.
-        # Actually in the spec it says: "Updates waypoint in waypoints table."
-        # This implies updating the closest waypoint or a generated waypoint path.
-        # We will follow the simplest form for now: update the waypoint if there is one corresponding.
-        # Let's say we update a waypoint with id "wp_{frame_id}" for now if we know how they map,
-        # or we just skip unless specified.
-
-        # 2. Trigger SSE event
-        evt = FrameProcessedEvent(
-            frame_id=frame_id,
-            gps=GPSPoint(lat=gps_lat, lon=gps_lon),
-            altitude=altitude,
-            confidence=confidence,
-            heading=heading,
-            timestamp=timestamp,
-        )
-        if refined:
-            self.sse.send_refinement(flight_id, evt)
-        else:
-            self.sse.send_frame_result(flight_id, evt)
-
-        return True
-
-    async def publish_waypoint_update(self, flight_id: str, frame_id: int) -> bool:
-        # Just delegates to SSE for waypoint updates, which is basically the frame result for UI
-        pass
+"""Legacy import path. Phase 1 shim — code lives in pipeline/result_manager.py."""
+from gps_denied.pipeline.result_manager import (  # noqa: F401
+    ResultManager,
+)

src/gps_denied/core/rotation.py

@@ -1,8 +1,9 @@
 """Image Rotation Manager (Component F06)."""
 
+import dataclasses
 import math
-from abc import ABC, abstractmethod
 from datetime import datetime
+from typing import Protocol, runtime_checkable
 
 import cv2
 import numpy as np
@@ -11,14 +12,14 @@ from gps_denied.schemas.rotation import HeadingHistory, RotationResult
 from gps_denied.schemas.satellite import TileBounds
 
 
-class IImageMatcher(ABC):
+@runtime_checkable
+class IImageMatcher(Protocol):
     """Dependency injection interface for Metric Refinement."""
-    @abstractmethod
     def align_to_satellite(
         self, uav_image: np.ndarray, satellite_tile: np.ndarray,
         tile_bounds: TileBounds,
     ) -> RotationResult:
-        pass
+        ...
 
 
 class ImageRotationManager:
@@ -77,8 +78,13 @@ class ImageRotationManager:
 
             if result.matched:
                 precise_angle = self.calculate_precise_angle(result.homography, float(angle))
-                result.precise_angle = precise_angle
-                result.initial_angle = float(angle)
+                # RotationResult is now a frozen dataclass (ARCH-02 / Plan 01-01);
+                # use `dataclasses.replace` instead of attribute assignment.
+                result = dataclasses.replace(
+                    result,
+                    precise_angle=precise_angle,
+                    initial_angle=float(angle),
+                )
 
                 self.update_heading(flight_id, frame_id, precise_angle, timestamp)
                 return result

src/gps_denied/core/satellite.py

@@ -1,287 +1,6 @@
-"""Satellite Data Manager (Component F04).
+"""Legacy import path. Phase 1 shim — code lives in components/satellite_matcher/."""
+from gps_denied.components.satellite_matcher.local_tile_loader import (  # noqa: F401
+    SatelliteDataManager,
+)
 
-SAT-01: Reads pre-loaded tiles from a local z/x/y directory (no live HTTP during flight).
-SAT-02: Tile selection uses ESKF position ± 3σ_horizontal to define search area.
-"""
-
-import hashlib
-import logging
-import math
-import os
-from concurrent.futures import ThreadPoolExecutor
-
-import cv2
-import numpy as np
-
-from gps_denied.schemas import GPSPoint
-from gps_denied.schemas.satellite import TileBounds, TileCoords
-from gps_denied.utils import mercator
-
-
-class SatelliteDataManager:
-    """Manages satellite tiles from a local pre-loaded directory.
-
-    Directory layout (SAT-01):
-        {tile_dir}/{zoom}/{x}/{y}.png   — standard Web Mercator slippy-map layout
-
-    No live HTTP requests are made during flight.  A separate offline tooling step
-    downloads and stores tiles before the mission.
-    """
-
-    _logger = logging.getLogger(__name__)
-
-    def __init__(
-        self,
-        tile_dir: str = ".satellite_tiles",
-        cache_dir: str = ".satellite_cache",
-        max_size_gb: float = 10.0,
-    ):
-        self.tile_dir = tile_dir
-        self.thread_pool = ThreadPoolExecutor(max_workers=4)
-        # In-memory LRU for hot tiles (avoids repeated disk reads)
-        self._mem_cache: dict[str, np.ndarray] = {}
-        self._mem_cache_max = 256
-        # SHA-256 manifest for tile integrity (якщо файл існує)
-        self._manifest: dict[str, str] = self._load_manifest()
-
-    # ------------------------------------------------------------------
-    # SAT-01: Local tile reads (no HTTP)
-    # ------------------------------------------------------------------
-
-    def _load_manifest(self) -> dict[str, str]:
-        """Завантажити SHA-256 manifest з tile_dir/manifest.sha256."""
-        path = os.path.join(self.tile_dir, "manifest.sha256")
-        if not os.path.isfile(path):
-            return {}
-        manifest: dict[str, str] = {}
-        with open(path) as f:
-            for line in f:
-                line = line.strip()
-                if not line or line.startswith("#"):
-                    continue
-                parts = line.split(maxsplit=1)
-                if len(parts) == 2:
-                    manifest[parts[1].strip()] = parts[0].strip()
-        return manifest
-
-    def _verify_tile_integrity(self, rel_path: str, file_path: str) -> bool:
-        """Перевірити SHA-256 тайла проти manifest (якщо manifest існує)."""
-        if not self._manifest:
-            return True  # без manifest — пропускаємо
-        expected = self._manifest.get(rel_path)
-        if expected is None:
-            return True  # тайл не в manifest — OK
-        sha = hashlib.sha256()
-        with open(file_path, "rb") as f:
-            for chunk in iter(lambda: f.read(8192), b""):
-                sha.update(chunk)
-        actual = sha.hexdigest()
-        if actual != expected:
-            self._logger.warning("Tile integrity failed: %s (exp %s, got %s)",
-                                rel_path, expected[:12], actual[:12])
-            return False
-        return True
-
-    def load_local_tile(self, tile_coords: TileCoords) -> np.ndarray | None:
-        """Load a tile image from the local pre-loaded directory.
-
-        Expected path: {tile_dir}/{zoom}/{x}/{y}.png
-        Returns None if the file does not exist.
-        """
-        key = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}"
-        if key in self._mem_cache:
-            return self._mem_cache[key]
-
-        rel_path = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}.png"
-        path = os.path.join(self.tile_dir, rel_path)
-        if not os.path.isfile(path):
-            return None
-
-        if not self._verify_tile_integrity(rel_path, path):
-            return None  # тайл пошкоджений
-
-        img = cv2.imread(path, cv2.IMREAD_COLOR)
-        if img is None:
-            return None
-
-        # LRU eviction: drop oldest if full
-        if len(self._mem_cache) >= self._mem_cache_max:
-            oldest = next(iter(self._mem_cache))
-            del self._mem_cache[oldest]
-        self._mem_cache[key] = img
-        return img
-
-    def save_local_tile(self, tile_coords: TileCoords, image: np.ndarray) -> bool:
-        """Persist a tile to the local directory (used by offline pre-fetch tooling)."""
-        path = os.path.join(self.tile_dir, str(tile_coords.zoom),
-                            str(tile_coords.x), f"{tile_coords.y}.png")
-        os.makedirs(os.path.dirname(path), exist_ok=True)
-        ok, encoded = cv2.imencode(".png", image)
-        if not ok:
-            return False
-        with open(path, "wb") as f:
-            f.write(encoded.tobytes())
-        key = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}"
-        self._mem_cache[key] = image
-        return True
-
-    # ------------------------------------------------------------------
-    # SAT-02: Tile selection for ESKF position ± 3σ_horizontal
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def _meters_to_degrees(meters: float, lat: float) -> tuple[float, float]:
-        """Convert a radius in metres to (Δlat°, Δlon°) at the given latitude."""
-        delta_lat = meters / 111_320.0
-        delta_lon = meters / (111_320.0 * math.cos(math.radians(lat)))
-        return delta_lat, delta_lon
-
-    def select_tiles_for_eskf_position(
-        self, gps: GPSPoint, sigma_h_m: float, zoom: int
-    ) -> list[TileCoords]:
-        """Return all tile coords covering the ESKF position ± 3σ_horizontal area.
-
-        Args:
-            gps:        ESKF best-estimate position.
-            sigma_h_m:  1-σ horizontal uncertainty in metres (from ESKF covariance).
-            zoom:       Web Mercator zoom level (18 recommended ≈ 0.6 m/px).
-        """
-        radius_m = 3.0 * sigma_h_m
-        dlat, dlon = self._meters_to_degrees(radius_m, gps.lat)
-
-        # Bounding box corners
-        lat_min, lat_max = gps.lat - dlat, gps.lat + dlat
-        lon_min, lon_max = gps.lon - dlon, gps.lon + dlon
-
-        # Convert corners to tile coords
-        tc_nw = mercator.latlon_to_tile(lat_max, lon_min, zoom)
-        tc_se = mercator.latlon_to_tile(lat_min, lon_max, zoom)
-
-        tiles: list[TileCoords] = []
-        for x in range(tc_nw.x, tc_se.x + 1):
-            for y in range(tc_nw.y, tc_se.y + 1):
-                tiles.append(TileCoords(x=x, y=y, zoom=zoom))
-        return tiles
-
-    def assemble_mosaic(
-        self,
-        tile_list: list[tuple[TileCoords, np.ndarray]],
-        target_size: int = 512,
-    ) -> tuple[np.ndarray, TileBounds] | None:
-        """Assemble a list of (TileCoords, image) pairs into a single mosaic.
-
-        Returns (mosaic_image, combined_bounds) or None if tile_list is empty.
-        The mosaic is resized to (target_size × target_size) for the matcher.
-        """
-        if not tile_list:
-            return None
-
-        xs = [tc.x for tc, _ in tile_list]
-        ys = [tc.y for tc, _ in tile_list]
-        zoom = tile_list[0][0].zoom
-
-        x_min, x_max = min(xs), max(xs)
-        y_min, y_max = min(ys), max(ys)
-
-        cols = x_max - x_min + 1
-        rows = y_max - y_min + 1
-
-        # Determine single-tile pixel size from first image
-        sample = tile_list[0][1]
-        th, tw = sample.shape[:2]
-
-        canvas = np.zeros((rows * th, cols * tw, 3), dtype=np.uint8)
-        for tc, img in tile_list:
-            col = tc.x - x_min
-            row = tc.y - y_min
-            h, w = img.shape[:2]
-            canvas[row * th: row * th + h, col * tw: col * tw + w] = img
-
-        mosaic = cv2.resize(canvas, (target_size, target_size), interpolation=cv2.INTER_AREA)
-
-        # Compute combined GPS bounds
-        nw_bounds = mercator.compute_tile_bounds(TileCoords(x=x_min, y=y_min, zoom=zoom))
-        se_bounds = mercator.compute_tile_bounds(TileCoords(x=x_max, y=y_max, zoom=zoom))
-        combined = TileBounds(
-            nw=nw_bounds.nw,
-            ne=GPSPoint(lat=nw_bounds.nw.lat, lon=se_bounds.se.lon),
-            sw=GPSPoint(lat=se_bounds.se.lat, lon=nw_bounds.nw.lon),
-            se=se_bounds.se,
-            center=GPSPoint(
-                lat=(nw_bounds.nw.lat + se_bounds.se.lat) / 2,
-                lon=(nw_bounds.nw.lon + se_bounds.se.lon) / 2,
-            ),
-            gsd=nw_bounds.gsd,
-        )
-        return mosaic, combined
-
-    def fetch_tiles_for_position(
-        self, gps: GPSPoint, sigma_h_m: float, zoom: int
-    ) -> tuple[np.ndarray, TileBounds] | None:
-        """High-level helper: select tiles + load + assemble mosaic.
-
-        Returns (mosaic, bounds) or None if no local tiles are available.
-        """
-        coords = self.select_tiles_for_eskf_position(gps, sigma_h_m, zoom)
-        loaded: list[tuple[TileCoords, np.ndarray]] = []
-        for tc in coords:
-            img = self.load_local_tile(tc)
-            if img is not None:
-                loaded.append((tc, img))
-        return self.assemble_mosaic(loaded) if loaded else None
-
-    # ------------------------------------------------------------------
-    # Cache helpers (backward-compat, also used for warm-path caching)
-    # ------------------------------------------------------------------
-
-    def cache_tile(self, flight_id: str, tile_coords: TileCoords, tile_data: np.ndarray) -> bool:
-        """Cache a tile image in memory (used by tests and offline tools)."""
-        key = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}"
-        self._mem_cache[key] = tile_data
-        return True
-
-    def get_cached_tile(self, flight_id: str, tile_coords: TileCoords) -> np.ndarray | None:
-        """Retrieve a cached tile from memory."""
-        key = f"{tile_coords.zoom}/{tile_coords.x}/{tile_coords.y}"
-        return self._mem_cache.get(key)
-
-    # ------------------------------------------------------------------
-    # Tile math helpers
-    # ------------------------------------------------------------------
-
-    def get_tile_grid(self, center: TileCoords, grid_size: int) -> list[TileCoords]:
-        """Return grid_size tiles centered on center."""
-        if grid_size == 1:
-            return [center]
-
-        side = int(grid_size ** 0.5)
-        half = side // 2
-
-        coords: list[TileCoords] = []
-        for dy in range(-half, half + 1):
-            for dx in range(-half, half + 1):
-                coords.append(TileCoords(x=center.x + dx, y=center.y + dy, zoom=center.zoom))
-
-        if grid_size == 4:
-            coords = []
-            for dy in range(2):
-                for dx in range(2):
-                    coords.append(TileCoords(x=center.x + dx, y=center.y + dy, zoom=center.zoom))
-
-        return coords[:grid_size]
-
-    def expand_search_grid(self, center: TileCoords, current_size: int, new_size: int) -> list[TileCoords]:
-        """Return only the NEW tiles when expanding from current_size to new_size grid."""
-        old_set = {(c.x, c.y) for c in self.get_tile_grid(center, current_size)}
-        return [c for c in self.get_tile_grid(center, new_size) if (c.x, c.y) not in old_set]
-
-    def compute_tile_coords(self, lat: float, lon: float, zoom: int) -> TileCoords:
-        return mercator.latlon_to_tile(lat, lon, zoom)
-
-    def compute_tile_bounds(self, tile_coords: TileCoords) -> TileBounds:
-        return mercator.compute_tile_bounds(tile_coords)
-
-    def clear_flight_cache(self, flight_id: str) -> bool:
-        """Clear in-memory cache (flight scoping is tile-key-based)."""
-        self._mem_cache.clear()
-        return True
+__all__ = ["SatelliteDataManager"]

src/gps_denied/core/sse.py

@@ -1,164 +1,4 @@
-"""SSE Event Streamer (Component F15)."""
-
-from __future__ import annotations
-
-import asyncio
-import json
-from collections import defaultdict
-
-from gps_denied.schemas.events import (
-    FlightCompletedEvent,
-    FrameProcessedEvent,
-    SearchExpandedEvent,
-    SSEEventType,
-    SSEMessage,
-    UserInputNeededEvent,
+"""Legacy import path. Phase 1 shim — code lives in pipeline/sse_streamer.py."""
+from gps_denied.pipeline.sse_streamer import (  # noqa: F401
+    SSEEventStreamer,
 )
-
-
-class SSEEventStreamer:
-    """Manages real-time SSE connections and event broadcasting."""
-
-    def __init__(self) -> None:
-        # Map: flight_id -> Dict[client_id, asyncio.Queue]
-        self._streams: dict[str, dict[str, asyncio.Queue[SSEMessage | None]]] = defaultdict(dict)
-
-    def create_stream(self, flight_id: str, client_id: str) -> asyncio.Queue[SSEMessage | None]:
-        """Create a new event queue for a client."""
-        q: asyncio.Queue[SSEMessage | None] = asyncio.Queue()
-        self._streams[flight_id][client_id] = q
-        return q
-
-    def close_stream(self, flight_id: str, client_id: str) -> None:
-        """Close a client stream by putting a sentinel and removing the queue."""
-        if flight_id in self._streams and client_id in self._streams[flight_id]:
-            q = self._streams[flight_id].pop(client_id)
-            if not self._streams[flight_id]:
-                del self._streams[flight_id]
-            # Put None to signal generator exit
-            try:
-                q.put_nowait(None)
-            except asyncio.QueueFull:
-                pass
-
-    def get_active_connections(self, flight_id: str) -> int:
-        return len(self._streams.get(flight_id, {}))
-
-    def _broadcast(self, flight_id: str, msg: SSEMessage) -> bool:
-        """Broadcast a message to all clients subscribed to flight_id."""
-        if flight_id not in self._streams or not self._streams[flight_id]:
-            return False
-
-        for q in self._streams[flight_id].values():
-            try:
-                q.put_nowait(msg)
-            except asyncio.QueueFull:
-                pass  # Drop if queue is full rather than blocking
-        return True
-
-    # ── Business Event Senders ────────────────────────────────────────────────
-
-    def send_frame_result(self, flight_id: str, event_data: FrameProcessedEvent) -> bool:
-        msg = SSEMessage(
-            event=SSEEventType.FRAME_PROCESSED,
-            data=event_data.model_dump(mode="json"),
-            id=f"frame_{event_data.frame_id}",
-        )
-        return self._broadcast(flight_id, msg)
-
-    def send_refinement(self, flight_id: str, event_data: FrameProcessedEvent) -> bool:
-        msg = SSEMessage(
-            event=SSEEventType.FRAME_REFINED,
-            data=event_data.model_dump(mode="json"),
-            id=f"refine_{event_data.frame_id}",
-        )
-        return self._broadcast(flight_id, msg)
-
-    def send_search_progress(self, flight_id: str, event_data: SearchExpandedEvent) -> bool:
-        msg = SSEMessage(
-            event=SSEEventType.SEARCH_EXPANDED,
-            data=event_data.model_dump(mode="json"),
-        )
-        return self._broadcast(flight_id, msg)
-
-    def send_user_input_request(self, flight_id: str, event_data: UserInputNeededEvent) -> bool:
-        msg = SSEMessage(
-            event=SSEEventType.USER_INPUT_NEEDED,
-            data=event_data.model_dump(mode="json"),
-        )
-        return self._broadcast(flight_id, msg)
-
-    def send_flight_completed(self, flight_id: str, event_data: FlightCompletedEvent) -> bool:
-        msg = SSEMessage(
-            event=SSEEventType.FLIGHT_COMPLETED,
-            data=event_data.model_dump(mode="json"),
-        )
-        return self._broadcast(flight_id, msg)
-
-    def send_heartbeat(self, flight_id: str) -> bool:
-        # sse_starlette uses empty string or comment for heartbeat,
-        # but we can just send an SSEMessage object that parses as empty event
-        if flight_id not in self._streams:
-            return False
-
-        # Manually sending a comment via the generator is tricky with strict SSEMessage schema
-        # but we'll handle this in the stream generator directly
-        return True
-
-    # ── Generic event dispatcher (used by processor.process_frame) ──────────
-
-    async def push_event(self, flight_id: str, event_type: str, data: dict) -> None:
-        """Dispatch a generic event to all clients for a flight.
-
-        Maps event_type strings to typed SSE events:
-          "frame_result"  → FrameProcessedEvent
-          "refinement"    → FrameProcessedEvent (refined)
-          Other           → raw broadcast via SSEMessage
-        """
-        if event_type == "frame_result":
-            evt = FrameProcessedEvent(**data) if not isinstance(data, FrameProcessedEvent) else data
-            self.send_frame_result(flight_id, evt)
-        elif event_type == "refinement":
-            evt = FrameProcessedEvent(**data) if not isinstance(data, FrameProcessedEvent) else data
-            self.send_refinement(flight_id, evt)
-        else:
-            msg = SSEMessage(
-                event=SSEEventType.FRAME_PROCESSED,
-                data=data,
-                id=str(data.get("frame_id", "")),
-            )
-            self._broadcast(flight_id, msg)
-
-    # ── Stream Generator ──────────────────────────────────────────────────────
-
-    async def stream_generator(self, flight_id: str, client_id: str):
-        """Yields dicts for sse_starlette EventSourceResponse."""
-        q = self.create_stream(flight_id, client_id)
-
-        # Send an immediate connection accepted ping
-        yield {"event": "connected", "data": "connected"}
-
-        try:
-            while True:
-                # Wait for next event or send heartbeat every 15s
-                try:
-                    msg = await asyncio.wait_for(q.get(), timeout=15.0)
-                    if msg is None:
-                        # Sentinel for clean shutdown
-                        break
-
-                    # Yield dict format for sse_starlette
-                    yield {
-                        "event": msg.event.value,
-                        "id": msg.id if msg.id else "",
-                        "data": json.dumps(msg.data)
-                    }
-
-                except asyncio.TimeoutError:
-                    # Heartbeat format for sse_starlette (empty string generates a comment)
-                    yield {"event": "heartbeat", "data": "ping"}
-
-        except asyncio.CancelledError:
-            pass  # Client disconnected
-        finally:
-            self.close_stream(flight_id, client_id)

src/gps_denied/core/vo.py

@@ -1,575 +1,32 @@
-"""Sequential Visual Odometry (Component F07).
+"""Legacy import path for VIO. Phase 1 shim — code lives in components/vio/.
 
-Three concrete backends:
-  - SequentialVisualOdometry  — SuperPoint + LightGlue (TRT on Jetson / Mock on dev)
-  - ORBVisualOdometry         — OpenCV ORB + BFMatcher (dev/CI stub, VO-02)
-  - CuVSLAMVisualOdometry     — NVIDIA cuVSLAM Inertial mode (Jetson only, VO-01)
-
-Factory: create_vo_backend() selects the right one at runtime.
+This shim preserves ``from gps_denied.core.vo import ...`` for tests that
+were green at the start of Phase 1. Future phases may migrate test
+imports to the new path; the shim is removed in Phase 2 (TEST-01
+reorganization).
 """
-
-import logging
-from abc import ABC, abstractmethod
-from typing import Optional
-
-import cv2
-import numpy as np
-
-from gps_denied.core.models import IModelManager
-from gps_denied.schemas import CameraParameters
-from gps_denied.schemas.vo import Features, Matches, Motion, RelativePose
-
-logger = logging.getLogger(__name__)
-
-
-class ISequentialVisualOdometry(ABC):
-    @abstractmethod
-    def compute_relative_pose(
-        self, prev_image: np.ndarray, curr_image: np.ndarray, camera_params: CameraParameters
-    ) -> RelativePose | None:
-        pass
-
-    @abstractmethod
-    def extract_features(self, image: np.ndarray) -> Features:
-        pass
-
-    @abstractmethod
-    def match_features(self, features1: Features, features2: Features) -> Matches:
-        pass
-
-    @abstractmethod
-    def estimate_motion(self, matches: Matches, camera_params: CameraParameters) -> Motion | None:
-        pass
-
-
-class SequentialVisualOdometry(ISequentialVisualOdometry):
-    """Frame-to-frame visual odometry using SuperPoint + LightGlue."""
-
-    def __init__(self, model_manager: IModelManager):
-        self.model_manager = model_manager
-
-    def extract_features(self, image: np.ndarray) -> Features:
-        """Extracts keypoints and descriptors using SuperPoint."""
-        engine = self.model_manager.get_inference_engine("SuperPoint")
-        result = engine.infer(image)
-
-        return Features(
-            keypoints=result["keypoints"],
-            descriptors=result["descriptors"],
-            scores=result["scores"]
-        )
-
-    def match_features(self, features1: Features, features2: Features) -> Matches:
-        """Matches features using LightGlue."""
-        engine = self.model_manager.get_inference_engine("LightGlue")
-        result = engine.infer({
-            "features1": features1,
-            "features2": features2
-        })
-
-        return Matches(
-            matches=result["matches"],
-            scores=result["scores"],
-            keypoints1=result["keypoints1"],
-            keypoints2=result["keypoints2"]
-        )
-
-    def estimate_motion(self, matches: Matches, camera_params: CameraParameters) -> Motion | None:
-        """Estimates camera motion using Essential Matrix (RANSAC)."""
-        inlier_threshold = 20
-        if len(matches.matches) < 8:
-            return None
-
-        pts1 = np.ascontiguousarray(matches.keypoints1)
-        pts2 = np.ascontiguousarray(matches.keypoints2)
-
-        # Build camera matrix
-        f_px = camera_params.focal_length * (camera_params.resolution_width / camera_params.sensor_width)
-        if camera_params.principal_point:
-            cx, cy = camera_params.principal_point
-        else:
-            cx = camera_params.resolution_width / 2.0
-            cy = camera_params.resolution_height / 2.0
-
-        K = np.array([
-            [f_px, 0, cx],
-            [0, f_px, cy],
-            [0, 0,  1]
-        ], dtype=np.float64)
-
-        try:
-            E, inliers = cv2.findEssentialMat(
-                pts1, pts2, cameraMatrix=K, method=cv2.RANSAC, prob=0.999, threshold=1.0
-            )
-        except Exception as e:
-            logger.error(f"Error finding essential matrix: {e}")
-            return None
-
-        if E is None or E.shape != (3, 3):
-            return None
-
-        inliers_mask = inliers.flatten().astype(bool)
-        inlier_count = np.sum(inliers_mask)
-
-        if inlier_count < inlier_threshold:
-            logger.warning(f"Insufficient inliers: {inlier_count} < {inlier_threshold}")
-            return None
-
-        # Recover pose
-        try:
-            _, R, t, mask = cv2.recoverPose(E, pts1, pts2, cameraMatrix=K, mask=inliers)
-        except Exception as e:
-            logger.error(f"Error recovering pose: {e}")
-            return None
-
-        return Motion(
-            translation=t.flatten(),
-            rotation=R,
-            inliers=inliers_mask,
-            inlier_count=inlier_count
-        )
-
-    def compute_relative_pose(
-        self, prev_image: np.ndarray, curr_image: np.ndarray, camera_params: CameraParameters
-    ) -> RelativePose | None:
-        """Computes relative pose between two frames."""
-        f1 = self.extract_features(prev_image)
-        f2 = self.extract_features(curr_image)
-
-        matches = self.match_features(f1, f2)
-
-        motion = self.estimate_motion(matches, camera_params)
-
-        if motion is None:
-            return None
-
-        tracking_good = motion.inlier_count > 50
-
-        return RelativePose(
-            translation=motion.translation,
-            rotation=motion.rotation,
-            confidence=float(motion.inlier_count / max(1, len(matches.matches))),
-            inlier_count=motion.inlier_count,
-            total_matches=len(matches.matches),
-            tracking_good=tracking_good,
-            scale_ambiguous=True,
-        )
-
-
-# ---------------------------------------------------------------------------
-# ORBVisualOdometry — OpenCV ORB stub for dev/CI (VO-02)
-# ---------------------------------------------------------------------------
-
-class ORBVisualOdometry(ISequentialVisualOdometry):
-    """OpenCV ORB-based VO stub for x86 dev/CI environments.
-
-    Satisfies the same ISequentialVisualOdometry interface as the cuVSLAM wrapper.
-    Translation is unit-scale (scale_ambiguous=True) — metric scale requires ESKF.
-    """
-
-    _MIN_INLIERS = 20
-    _N_FEATURES = 2000
-
-    def __init__(self):
-        self._orb = cv2.ORB_create(nfeatures=self._N_FEATURES)
-        self._matcher = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=False)
-
-    # ------------------------------------------------------------------
-    # ISequentialVisualOdometry interface
-    # ------------------------------------------------------------------
-
-    def extract_features(self, image: np.ndarray) -> Features:
-        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if image.ndim == 3 else image
-        kps, descs = self._orb.detectAndCompute(gray, None)
-        if descs is None or len(kps) == 0:
-            return Features(
-                keypoints=np.zeros((0, 2), dtype=np.float32),
-                descriptors=np.zeros((0, 32), dtype=np.uint8),
-                scores=np.zeros(0, dtype=np.float32),
-            )
-        pts = np.array([[k.pt[0], k.pt[1]] for k in kps], dtype=np.float32)
-        scores = np.array([k.response for k in kps], dtype=np.float32)
-        return Features(keypoints=pts, descriptors=descs.astype(np.float32), scores=scores)
-
-    def match_features(self, features1: Features, features2: Features) -> Matches:
-        if len(features1.keypoints) == 0 or len(features2.keypoints) == 0:
-            return Matches(
-                matches=np.zeros((0, 2), dtype=np.int32),
-                scores=np.zeros(0, dtype=np.float32),
-                keypoints1=np.zeros((0, 2), dtype=np.float32),
-                keypoints2=np.zeros((0, 2), dtype=np.float32),
-            )
-        d1 = features1.descriptors.astype(np.uint8)
-        d2 = features2.descriptors.astype(np.uint8)
-        raw = self._matcher.knnMatch(d1, d2, k=2)
-        # Lowe ratio test
-        good = []
-        for pair in raw:
-            if len(pair) == 2 and pair[0].distance < 0.75 * pair[1].distance:
-                good.append(pair[0])
-        if not good:
-            return Matches(
-                matches=np.zeros((0, 2), dtype=np.int32),
-                scores=np.zeros(0, dtype=np.float32),
-                keypoints1=np.zeros((0, 2), dtype=np.float32),
-                keypoints2=np.zeros((0, 2), dtype=np.float32),
-            )
-        idx = np.array([[m.queryIdx, m.trainIdx] for m in good], dtype=np.int32)
-        scores = np.array([1.0 / (1.0 + m.distance) for m in good], dtype=np.float32)
-        kp1 = features1.keypoints[idx[:, 0]]
-        kp2 = features2.keypoints[idx[:, 1]]
-        return Matches(matches=idx, scores=scores, keypoints1=kp1, keypoints2=kp2)
-
-    def estimate_motion(self, matches: Matches, camera_params: CameraParameters) -> Optional[Motion]:
-        if len(matches.matches) < 8:
-            return None
-        pts1 = np.ascontiguousarray(matches.keypoints1, dtype=np.float64)
-        pts2 = np.ascontiguousarray(matches.keypoints2, dtype=np.float64)
-        f_px = camera_params.focal_length * (
-            camera_params.resolution_width / camera_params.sensor_width
-        )
-        cx = (camera_params.principal_point[0]
-              if camera_params.principal_point
-              else camera_params.resolution_width / 2.0)
-        cy = (camera_params.principal_point[1]
-              if camera_params.principal_point
-              else camera_params.resolution_height / 2.0)
-        K = np.array([[f_px, 0, cx], [0, f_px, cy], [0, 0, 1]], dtype=np.float64)
-        try:
-            E, inliers = cv2.findEssentialMat(pts1, pts2, cameraMatrix=K, method=cv2.RANSAC, prob=0.999, threshold=1.0)
-        except Exception as exc:
-            logger.warning("ORB findEssentialMat failed: %s", exc)
-            return None
-        if E is None or E.shape != (3, 3) or inliers is None:
-            return None
-        inlier_mask = inliers.flatten().astype(bool)
-        inlier_count = int(np.sum(inlier_mask))
-        if inlier_count < self._MIN_INLIERS:
-            return None
-        try:
-            _, R, t, mask = cv2.recoverPose(E, pts1, pts2, cameraMatrix=K, mask=inliers)
-        except Exception as exc:
-            logger.warning("ORB recoverPose failed: %s", exc)
-            return None
-        return Motion(translation=t.flatten(), rotation=R, inliers=inlier_mask, inlier_count=inlier_count)
-
-    def compute_relative_pose(
-        self, prev_image: np.ndarray, curr_image: np.ndarray, camera_params: CameraParameters
-    ) -> Optional[RelativePose]:
-        f1 = self.extract_features(prev_image)
-        f2 = self.extract_features(curr_image)
-        matches = self.match_features(f1, f2)
-        motion = self.estimate_motion(matches, camera_params)
-        if motion is None:
-            return None
-        tracking_good = motion.inlier_count >= self._MIN_INLIERS
-        return RelativePose(
-            translation=motion.translation,
-            rotation=motion.rotation,
-            confidence=float(motion.inlier_count / max(1, len(matches.matches))),
-            inlier_count=motion.inlier_count,
-            total_matches=len(matches.matches),
-            tracking_good=tracking_good,
-            scale_ambiguous=True,  # monocular ORB cannot recover metric scale
-        )
-
-
-# ---------------------------------------------------------------------------
-# CuVSLAMVisualOdometry — NVIDIA cuVSLAM Inertial mode (Jetson, VO-01)
-# ---------------------------------------------------------------------------
-
-class CuVSLAMVisualOdometry(ISequentialVisualOdometry):
-    """cuVSLAM wrapper for Jetson Orin (Inertial mode).
-
-    Provides metric relative poses in NED (scale_ambiguous=False).
-    Falls back to ORBVisualOdometry internally when the cuVSLAM SDK is absent
-    so the same class can be instantiated on dev/CI with scale_ambiguous reflecting
-    the actual backend capability.
-
-    Usage on Jetson:
-        vo = CuVSLAMVisualOdometry(camera_params, imu_params)
-        pose = vo.compute_relative_pose(prev, curr, cam)  # scale_ambiguous=False
-    """
-
-    def __init__(self, camera_params: Optional[CameraParameters] = None, imu_params: Optional[dict] = None):
-        self._camera_params = camera_params
-        self._imu_params = imu_params or {}
-        self._cuvslam = None
-        self._tracker = None
-        self._orb_fallback = ORBVisualOdometry()
-
-        try:
-            import cuvslam  # type: ignore  # only available on Jetson
-            self._cuvslam = cuvslam
-            self._init_tracker()
-            logger.info("CuVSLAMVisualOdometry: cuVSLAM SDK loaded (Jetson mode)")
-        except ImportError:
-            logger.info("CuVSLAMVisualOdometry: cuVSLAM not available — using ORB fallback (dev/CI mode)")
-
-    def _init_tracker(self):
-        """Initialise cuVSLAM tracker in Inertial mode."""
-        if self._cuvslam is None:
-            return
-        try:
-            cam = self._camera_params
-            rig_params = self._cuvslam.CameraRigParams()
-            if cam is not None:
-                f_px = cam.focal_length * (cam.resolution_width / cam.sensor_width)
-                cx = cam.principal_point[0] if cam.principal_point else cam.resolution_width / 2.0
-                cy = cam.principal_point[1] if cam.principal_point else cam.resolution_height / 2.0
-                rig_params.cameras[0].intrinsics = self._cuvslam.CameraIntrinsics(
-                    fx=f_px, fy=f_px, cx=cx, cy=cy,
-                    width=cam.resolution_width, height=cam.resolution_height,
-                )
-            tracker_params = self._cuvslam.TrackerParams()
-            tracker_params.use_imu = True
-            tracker_params.imu_noise_model = self._cuvslam.ImuNoiseModel(
-                accel_noise=self._imu_params.get("accel_noise", 0.01),
-                gyro_noise=self._imu_params.get("gyro_noise", 0.001),
-            )
-            self._tracker = self._cuvslam.Tracker(rig_params, tracker_params)
-            logger.info("cuVSLAM tracker initialised in Inertial mode")
-        except Exception as exc:
-            logger.error("cuVSLAM tracker init failed: %s", exc)
-            self._cuvslam = None
-
-    @property
-    def _has_cuvslam(self) -> bool:
-        return self._cuvslam is not None and self._tracker is not None
-
-    # ------------------------------------------------------------------
-    # ISequentialVisualOdometry interface — delegate to cuVSLAM or ORB
-    # ------------------------------------------------------------------
-
-    def extract_features(self, image: np.ndarray) -> Features:
-        return self._orb_fallback.extract_features(image)
-
-    def match_features(self, features1: Features, features2: Features) -> Matches:
-        return self._orb_fallback.match_features(features1, features2)
-
-    def estimate_motion(self, matches: Matches, camera_params: CameraParameters) -> Optional[Motion]:
-        return self._orb_fallback.estimate_motion(matches, camera_params)
-
-    def compute_relative_pose(
-        self, prev_image: np.ndarray, curr_image: np.ndarray, camera_params: CameraParameters
-    ) -> Optional[RelativePose]:
-        if self._has_cuvslam:
-            return self._compute_via_cuvslam(curr_image, camera_params)
-        # Dev/CI fallback — ORB with scale_ambiguous still marked False to signal
-        # this class is *intended* as the metric backend (ESKF provides scale externally)
-        pose = self._orb_fallback.compute_relative_pose(prev_image, curr_image, camera_params)
-        if pose is None:
-            return None
-        return RelativePose(
-            translation=pose.translation,
-            rotation=pose.rotation,
-            confidence=pose.confidence,
-            inlier_count=pose.inlier_count,
-            total_matches=pose.total_matches,
-            tracking_good=pose.tracking_good,
-            scale_ambiguous=False,  # VO-04: cuVSLAM Inertial = metric; ESKF provides scale ref on dev
-        )
-
-    def _compute_via_cuvslam(self, image: np.ndarray, camera_params: CameraParameters) -> Optional[RelativePose]:
-        """Run cuVSLAM tracking step and convert result to RelativePose."""
-        try:
-            result = self._tracker.track(image)
-            if result is None or not result.tracking_ok:
-                return None
-            R = np.array(result.rotation).reshape(3, 3)
-            t = np.array(result.translation)
-            return RelativePose(
-                translation=t,
-                rotation=R,
-                confidence=float(getattr(result, "confidence", 1.0)),
-                inlier_count=int(getattr(result, "inlier_count", 100)),
-                total_matches=int(getattr(result, "total_matches", 100)),
-                tracking_good=True,
-                scale_ambiguous=False,  # VO-04: cuVSLAM Inertial mode = metric NED
-            )
-        except Exception as exc:
-            logger.error("cuVSLAM tracking step failed: %s", exc)
-            return None
-
-
-# ---------------------------------------------------------------------------
-# CuVSLAMMonoDepthVisualOdometry — cuVSLAM Mono-Depth mode (sprint 1 production)
-# ---------------------------------------------------------------------------
-# TODO(sprint 2): collapse duplicated SDK-load / _init_tracker scaffolding with
-# CuVSLAMVisualOdometry once Inertial mode is removed. Kept separate for sprint 1
-# so the Inertial → Mono-Depth migration is reversible.
-
-# Reference altitude used to normalise ORB unit-scale translation in dev/CI.
-# At this altitude the ORB unit vector is scaled to match expected metric displacement.
-_MONO_DEPTH_REFERENCE_ALTITUDE_M = 600.0
-
-
-class CuVSLAMMonoDepthVisualOdometry(ISequentialVisualOdometry):
-    """cuVSLAM Mono-Depth wrapper — barometer altitude as synthetic depth.
-
-    Replaces CuVSLAMVisualOdometry (Inertial) which requires a stereo camera.
-    cuVSLAM Mono-Depth accepts a depth hint (barometric altitude) to recover
-    metric scale from a single nadir camera.
-
-    On dev/CI (no cuVSLAM SDK): falls back to ORBVisualOdometry and scales
-    translation by depth_hint_m / _MONO_DEPTH_REFERENCE_ALTITUDE_M so that
-    the dev/CI metric magnitude is consistent with the Jetson production output.
-
-    Note — solution.md records OdometryMode=INERTIAL which requires stereo.
-    This class uses OdometryMode=MONO_DEPTH, the correct mode for our hardware.
-    Decision recorded in docs/superpowers/specs/2026-04-18-oss-stack-tech-audit-design.md.
-    """
-
-    def __init__(
-        self,
-        depth_hint_m: float = _MONO_DEPTH_REFERENCE_ALTITUDE_M,
-        camera_params: Optional[CameraParameters] = None,
-        imu_params: Optional[dict] = None,
-    ):
-        self._depth_hint_m = depth_hint_m
-        self._camera_params = camera_params
-        self._imu_params = imu_params or {}
-        self._cuvslam = None
-        self._tracker = None
-        self._orb_fallback = ORBVisualOdometry()
-
-        try:
-            import cuvslam  # type: ignore
-            self._cuvslam = cuvslam
-            self._init_tracker()
-            logger.info("CuVSLAMMonoDepthVisualOdometry: cuVSLAM SDK loaded (Jetson Mono-Depth mode)")
-        except ImportError:
-            logger.info("CuVSLAMMonoDepthVisualOdometry: cuVSLAM not available — using scaled ORB fallback")
-
-    def update_depth_hint(self, depth_hint_m: float) -> None:
-        """Update barometric altitude used for scale recovery. Call each frame."""
-        self._depth_hint_m = max(depth_hint_m, 1.0)
-
-    def _init_tracker(self) -> None:
-        if self._cuvslam is None:
-            return
-        try:
-            cam = self._camera_params
-            rig_params = self._cuvslam.CameraRigParams()
-            if cam is not None:
-                f_px = cam.focal_length * (cam.resolution_width / cam.sensor_width)
-                cx = cam.principal_point[0] if cam.principal_point else cam.resolution_width / 2.0
-                cy = cam.principal_point[1] if cam.principal_point else cam.resolution_height / 2.0
-                rig_params.cameras[0].intrinsics = self._cuvslam.CameraIntrinsics(
-                    fx=f_px, fy=f_px, cx=cx, cy=cy,
-                    width=cam.resolution_width, height=cam.resolution_height,
-                )
-            tracker_params = self._cuvslam.TrackerParams()
-            tracker_params.use_imu = False
-            tracker_params.odometry_mode = self._cuvslam.OdometryMode.MONO_DEPTH
-            self._tracker = self._cuvslam.Tracker(rig_params, tracker_params)
-            logger.info("cuVSLAM tracker initialised in Mono-Depth mode")
-        except Exception:
-            logger.exception(
-                "cuVSLAM Mono-Depth tracker init FAILED — falling back to ORB. "
-                "Production Jetson path is DISABLED until this is fixed."
-            )
-            self._cuvslam = None
-
-    @property
-    def _has_cuvslam(self) -> bool:
-        return self._cuvslam is not None and self._tracker is not None
-
-    def extract_features(self, image: np.ndarray) -> Features:
-        return self._orb_fallback.extract_features(image)
-
-    def match_features(self, features1: Features, features2: Features) -> Matches:
-        return self._orb_fallback.match_features(features1, features2)
-
-    def estimate_motion(self, matches: Matches, camera_params: CameraParameters) -> Optional[Motion]:
-        return self._orb_fallback.estimate_motion(matches, camera_params)
-
-    def compute_relative_pose(
-        self,
-        prev_image: np.ndarray,
-        curr_image: np.ndarray,
-        camera_params: CameraParameters,
-    ) -> Optional[RelativePose]:
-        if self._has_cuvslam:
-            return self._compute_via_cuvslam(curr_image)
-        return self._compute_via_orb_scaled(prev_image, curr_image, camera_params)
-
-    def _compute_via_cuvslam(self, image: np.ndarray) -> Optional[RelativePose]:
-        try:
-            result = self._tracker.track(image, depth_hint=self._depth_hint_m)
-            if result is None or not result.tracking_ok:
-                return None
-            return RelativePose(
-                translation=np.array(result.translation),
-                rotation=np.array(result.rotation).reshape(3, 3),
-                confidence=float(getattr(result, "confidence", 1.0)),
-                inlier_count=int(getattr(result, "inlier_count", 100)),
-                total_matches=int(getattr(result, "total_matches", 100)),
-                tracking_good=True,
-                scale_ambiguous=False,
-            )
-        except Exception:
-            logger.exception("cuVSLAM Mono-Depth tracking step failed — frame dropped")
-            return None
-
-    def _compute_via_orb_scaled(
-        self,
-        prev_image: np.ndarray,
-        curr_image: np.ndarray,
-        camera_params: CameraParameters,
-    ) -> Optional[RelativePose]:
-        """Dev/CI fallback: ORB translation scaled by depth_hint_m."""
-        pose = self._orb_fallback.compute_relative_pose(prev_image, curr_image, camera_params)
-        if pose is None:
-            return None
-        scale = self._depth_hint_m / _MONO_DEPTH_REFERENCE_ALTITUDE_M
-        return RelativePose(
-            translation=pose.translation * scale,
-            rotation=pose.rotation,
-            confidence=pose.confidence,
-            inlier_count=pose.inlier_count,
-            total_matches=pose.total_matches,
-            tracking_good=pose.tracking_good,
-            scale_ambiguous=False,
-        )
-
-
-# ---------------------------------------------------------------------------
-# Factory — selects appropriate VO backend at runtime
-# ---------------------------------------------------------------------------
-
-def create_vo_backend(
-    model_manager: Optional[IModelManager] = None,
-    prefer_cuvslam: bool = True,
-    prefer_mono_depth: bool = False,
-    camera_params: Optional[CameraParameters] = None,
-    imu_params: Optional[dict] = None,
-    depth_hint_m: float = 600.0,
-) -> ISequentialVisualOdometry:
-    """Return the best available VO backend for the current platform.
-
-    Priority when prefer_mono_depth=True:
-      1. CuVSLAMMonoDepthVisualOdometry (sprint 1 production path)
-      2. ORBVisualOdometry (dev/CI fallback inside Mono-Depth wrapper)
-
-    Priority when prefer_mono_depth=False (legacy):
-      1. CuVSLAMVisualOdometry (Jetson — cuVSLAM SDK present)
-      2. SequentialVisualOdometry (TRT/Mock SuperPoint+LightGlue)
-      3. ORBVisualOdometry (pure OpenCV fallback)
-    """
-    if prefer_mono_depth:
-        return CuVSLAMMonoDepthVisualOdometry(
-            depth_hint_m=depth_hint_m,
-            camera_params=camera_params,
-            imu_params=imu_params,
-        )
-
-    if prefer_cuvslam:
-        vo = CuVSLAMVisualOdometry(camera_params=camera_params, imu_params=imu_params)
-        if vo._has_cuvslam:
-            return vo
-
-    if model_manager is not None:
-        return SequentialVisualOdometry(model_manager)
-
-    return ORBVisualOdometry()
+from gps_denied.components.vio.cuvslam_backend import (
+    _CUVSLAM_AVAILABLE,
+    CuVSLAMMonoDepthVisualOdometry,
+    CuVSLAMVisualOdometry,
+)
+from gps_denied.components.vio.factory import create_vo_backend
+from gps_denied.components.vio.orbslam_backend import (
+    ORBVisualOdometry,
+    SequentialVisualOdometry,
+)
+from gps_denied.components.vio.protocol import (
+    ISequentialVisualOdometry,
+    VisualOdometry,
+)
+
+__all__ = [
+    "VisualOdometry",
+    "ISequentialVisualOdometry",
+    "ORBVisualOdometry",
+    "SequentialVisualOdometry",
+    "CuVSLAMVisualOdometry",
+    "CuVSLAMMonoDepthVisualOdometry",
+    "create_vo_backend",
+    "_CUVSLAM_AVAILABLE",
+]

src/gps_denied/hot_types/__init__.py

@@ -0,0 +1,66 @@
+"""Hot-path data types (ARCH-02).
+
+`@dataclass(slots=True, frozen=True)` types used per-frame on the
+critical path. Pydantic models stay at boundaries (REST/config/wire);
+this package replaces the per-frame Pydantic models from `schemas/`.
+
+Legacy import paths in `gps_denied.schemas.*` continue to work via
+re-export shims (Plan 01-01 Task 3).
+
+ARCH-02 canonical-name aliases:
+- `IMUMeasurement` → `IMUSample`
+- `VOEstimate`     → `RelativePose`
+"""
+
+from gps_denied.hot_types.alignment_result import (
+    AlignmentResult,
+    ChunkAlignmentResult,
+    Sim3Transform,
+)
+from gps_denied.hot_types.eskf_state import ESKFState
+from gps_denied.hot_types.frame_state import FrameState
+from gps_denied.hot_types.imu_sample import IMUSample
+from gps_denied.hot_types.position_estimate import PositionEstimate
+from gps_denied.hot_types.rotation_result import RotationResult
+from gps_denied.hot_types.satellite_anchor import (
+    SatelliteAnchor,
+    TileBounds,
+    TileCoords,
+)
+from gps_denied.hot_types.vo_estimate import (
+    Features,
+    Matches,
+    Motion,
+    RelativePose,
+    VOEstimate,
+)
+
+# ARCH-02 canonical-name aliases (legacy → new)
+IMUMeasurement = IMUSample
+
+__all__ = [
+    # ARCH-02 mandated names
+    "FrameState",
+    "IMUSample",
+    "PositionEstimate",
+    "VOEstimate",
+    "SatelliteAnchor",
+    # VIO outputs
+    "RelativePose",
+    "Features",
+    "Matches",
+    "Motion",
+    # ESKF
+    "ESKFState",
+    # Metric / alignment
+    "AlignmentResult",
+    "ChunkAlignmentResult",
+    "Sim3Transform",
+    # Rotation
+    "RotationResult",
+    # Satellite tile geometry
+    "TileCoords",
+    "TileBounds",
+    # Legacy aliases
+    "IMUMeasurement",
+]

src/gps_denied/hot_types/alignment_result.py

@@ -0,0 +1,54 @@
+"""Metric refinement hot-path dataclasses (ARCH-02).
+
+AlignmentResult, ChunkAlignmentResult, Sim3Transform — all returned per
+satellite-match frame.
+
+`gps_center` composes the still-Pydantic GPSPoint (deferred per
+PATTERNS.md §6.3); composition is fine.
+
+eq=False on every dataclass with np.ndarray fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from gps_denied.schemas import GPSPoint
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class AlignmentResult:
+    """Result of aligning a UAV image to a single satellite tile."""
+
+    matched: bool
+    homography: np.ndarray         # (3, 3)
+    gps_center: GPSPoint
+    confidence: float
+    inlier_count: int
+    total_correspondences: int
+    reprojection_error: float      # Mean error in pixels
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class Sim3Transform:
+    """Sim(3) transformation: scale, rotation, translation."""
+
+    translation: np.ndarray        # (3,)
+    rotation: np.ndarray           # (3, 3) rotation matrix
+    scale: float
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class ChunkAlignmentResult:
+    """Result of aligning a chunk array of UAV images to a satellite tile."""
+
+    matched: bool
+    chunk_id: str
+    chunk_center_gps: GPSPoint
+    rotation_angle: float
+    confidence: float
+    inlier_count: int
+    transform: Sim3Transform
+    reprojection_error: float

src/gps_denied/hot_types/eskf_state.py

@@ -0,0 +1,34 @@
+"""ESKFState hot-path dataclass (ARCH-02).
+
+Returned by `ESKF.get_state()` every frame. ConfidenceTier stays in
+schemas/eskf.py as an enum (boundary), and we import it here for the
+`confidence` field type.
+
+eq=False because numpy arrays in `__eq__` would raise; Pydantic was already
+incomparable for this model.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+from gps_denied.schemas.eskf import ConfidenceTier
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class ESKFState:
+    """Full ESKF nominal state snapshot."""
+
+    position: np.ndarray       # (3,) ENU meters from origin (East, North, Up)
+    velocity: np.ndarray       # (3,) ENU m/s
+    quaternion: np.ndarray     # (4,) [w, x, y, z] body-to-ENU
+    accel_bias: np.ndarray     # (3,) m/s^2
+    gyro_bias: np.ndarray      # (3,) rad/s
+    covariance: np.ndarray     # (15, 15)
+    timestamp: float           # seconds since epoch
+    confidence: ConfidenceTier
+    last_satellite_time: Optional[float] = None
+    last_vo_time: Optional[float] = None

src/gps_denied/hot_types/frame_state.py

@@ -0,0 +1,45 @@
+"""FrameState — per-frame mutable processing record (ARCH-02).
+
+PATTERNS.md §6.1 explicitly mandates `slots=True, frozen=False` here:
+processor.py mutates this object during frame handling. The field list
+mirrors the current `FrameResult` defined in `core/processor.py` lines
+~52-62. All fields default-initialize so the dataclass can be constructed
+with just `frame_id`, matching the existing `FrameResult(frame_id)`
+constructor signature.
+
+The actual rename of consumer call-sites from `FrameResult` to
+`FrameState` happens in Plan 07 (orchestrator rename); Phase 1 only
+introduces this type.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from gps_denied.schemas import GPSPoint
+
+
+# Forward import: TrackingState lives in core/processor.py today and is
+# moved here only as a type annotation. We avoid a hard import at module
+# level so that core/processor.py remains the source of truth in Phase 1.
+# Plan 07 will pull TrackingState into hot_types proper.
+TrackingState = "TrackingState"  # type: ignore[assignment]
+
+
+@dataclass(slots=True)
+class FrameState:
+    """Intermediate result of processing a single frame (mutable).
+
+    Mirrors stage1's `core.processor.FrameResult` field set; default
+    values let `FrameState(frame_id=N)` reconstruct the existing
+    `FrameResult(frame_id)` semantics.
+    """
+
+    frame_id: int = 0
+    gps: "Optional[GPSPoint]" = None
+    confidence: float = 0.0
+    tracking_state: str = "normal"   # mirrors TrackingState.NORMAL string value
+    vo_success: bool = False
+    alignment_success: bool = False

src/gps_denied/hot_types/imu_sample.py

@@ -0,0 +1,25 @@
+"""IMUSample hot-path dataclass (ARCH-02).
+
+Renamed from `IMUMeasurement` (Pydantic) per ARCH-02 canonical-name list.
+The legacy name is preserved as an alias from the schemas/eskf.py shim
+(`IMUMeasurement = IMUSample`), so existing import sites continue to work.
+
+eq=False because numpy arrays in `__eq__` would raise; Pydantic was already
+incomparable for this model (arbitrary_types_allowed), so dataclass behavior
+matches existing semantics.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class IMUSample:
+    """Single IMU reading from flight controller."""
+
+    accel: np.ndarray  # (3,) m/s^2 in body frame
+    gyro: np.ndarray   # (3,) rad/s in body frame
+    timestamp: float   # seconds since epoch

src/gps_denied/hot_types/position_estimate.py

@@ -0,0 +1,25 @@
+"""PositionEstimate hot-path dataclass (ARCH-02).
+
+NEW in Stage 2 — no stage1 analog. Phase 3 (SAFE-01..03) populates the
+Optional `source_label` and `anchor_age_ms` fields; Phase 1 only declares
+them so downstream code can be written against the final type.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(slots=True, frozen=True)
+class PositionEstimate:
+    """Unified per-frame position estimate emitted by the pipeline."""
+
+    lat: float
+    lon: float
+    alt: float
+    timestamp: float
+    confidence: float
+    covariance_semimajor_m: float = 0.0
+    source_label: Optional[str] = None     # filled in Phase 3 (SAFE)
+    anchor_age_ms: Optional[float] = None  # filled in Phase 3 (SAFE)

src/gps_denied/hot_types/rotation_result.py

@@ -0,0 +1,23 @@
+"""RotationResult hot-path dataclass (ARCH-02).
+
+eq=False because the optional `homography` is a numpy array.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class RotationResult:
+    """Result of a rotation sweep alignment."""
+
+    matched: bool
+    initial_angle: float
+    precise_angle: float
+    confidence: float
+    homography: Optional[np.ndarray] = None
+    inlier_count: int = 0

src/gps_denied/hot_types/satellite_anchor.py

@@ -0,0 +1,47 @@
+"""Satellite-anchor hot-path dataclasses (ARCH-02).
+
+TileCoords / TileBounds are hot during tile selection (per-frame).
+SatelliteAnchor is a Phase-1 placeholder — Phase 3 (VERIFY) fills its
+semantics. Phase 1 only requires it to exist for ARCH-02.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from gps_denied.schemas import GPSPoint
+
+
+@dataclass(slots=True, frozen=True)
+class TileCoords:
+    """Web Mercator tile coordinates."""
+
+    x: int
+    y: int
+    zoom: int
+
+
+@dataclass(slots=True, frozen=True)
+class TileBounds:
+    """GPS boundaries of a tile."""
+
+    nw: GPSPoint
+    ne: GPSPoint
+    sw: GPSPoint
+    se: GPSPoint
+    center: GPSPoint
+    gsd: float                     # Ground Sampling Distance (meters/pixel)
+
+
+@dataclass(slots=True, frozen=True)
+class SatelliteAnchor:
+    """Placeholder for Phase-3 verified satellite anchor record (ARCH-02).
+
+    Phase 1 declaration only — populated by Phase 3 (VERIFY). Carries the
+    minimum fields required for the ARCH-02 type-surface to exist.
+    """
+
+    gps_center: GPSPoint
+    timestamp: float
+    matched_inlier_count: int = 0
+    covariance_semimajor_m: float = 0.0

src/gps_denied/hot_types/vo_estimate.py

@@ -0,0 +1,73 @@
+"""Visual-odometry hot-path dataclasses (ARCH-02).
+
+Includes Features, Matches, RelativePose, Motion. `VOEstimate` is a
+module-level alias of `RelativePose` per ARCH-02 canonical-name list —
+the existing impl returns RelativePose; VOEstimate is the protocol-level
+name.
+
+eq=False on every dataclass that carries np.ndarray fields, matching
+Pydantic's prior incomparability under arbitrary_types_allowed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class Features:
+    """Extracted image features (e.g., from SuperPoint)."""
+
+    keypoints: np.ndarray      # (N, 2)
+    descriptors: np.ndarray    # (N, 256)
+    scores: np.ndarray         # (N,)
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class Matches:
+    """Matches between two sets of features (e.g., from LightGlue)."""
+
+    matches: np.ndarray        # (M, 2)
+    scores: np.ndarray         # (M,)
+    keypoints1: np.ndarray     # (M, 2)
+    keypoints2: np.ndarray     # (M, 2)
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class RelativePose:
+    """Relative pose between two frames.
+
+    Note: `covariance` is included as an optional 6×6 SE(3) uncertainty
+    matrix. The legacy Pydantic model did not declare this field but
+    silently accepted `covariance=...` kwargs (Pydantic v2 default
+    `extra="ignore"` behavior). Several stage1 tests rely on that
+    construction signature; declaring the field here preserves the
+    contract under the dataclass migration without editing tests.
+    """
+
+    translation: np.ndarray    # (3,)
+    rotation: np.ndarray       # (3, 3)
+    confidence: float
+    inlier_count: int
+    total_matches: int
+    tracking_good: bool
+    scale_ambiguous: bool = True
+    chunk_id: Optional[str] = None
+    covariance: Optional[np.ndarray] = None  # (6, 6) SE(3) covariance — optional
+
+
+@dataclass(slots=True, frozen=True, eq=False)
+class Motion:
+    """Motion estimate from OpenCV."""
+
+    translation: np.ndarray    # (3,) unit vector
+    rotation: np.ndarray       # (3, 3) rotation matrix
+    inliers: np.ndarray        # Boolean mask of inliers
+    inlier_count: int
+
+
+# ARCH-02 canonical name — VOEstimate IS the relative pose returned by VIO.
+VOEstimate = RelativePose

src/gps_denied/pipeline/__init__.py

@@ -0,0 +1,17 @@
+"""Pipeline package: orchestrator + IO + composition root."""
+from .orchestrator import FlightProcessor
+from .image_input import ImageInputPipeline
+from .result_manager import ResultManager
+from .sse_streamer import SSEEventStreamer
+from .composition import build_pipeline
+
+Pipeline = FlightProcessor
+
+__all__ = [
+    "FlightProcessor",
+    "Pipeline",
+    "ImageInputPipeline",
+    "ResultManager",
+    "SSEEventStreamer",
+    "build_pipeline",
+]

src/gps_denied/pipeline/composition.py

@@ -0,0 +1,155 @@
+"""Env-aware pipeline composition root (ARCH-01 / ARCH-03, Plan 08).
+
+``build_pipeline`` is the single entry point that wires all concrete adapters
+into a :class:`FlightProcessor`.  Callers in ``app.py`` and ``api/deps.py``
+should import this function rather than instantiating components directly.
+
+Env-conditional wiring
+----------------------
+- ``env="jetson"``        → prefer_cuvslam=True,  prefer_mono_depth=True
+- ``env="x86_dev"``       → prefer_cuvslam=False, prefer_mono_depth=False
+- ``env="ci"``            → prefer_cuvslam=False, prefer_mono_depth=False
+- ``env="sitl"``          → prefer_cuvslam=False, prefer_mono_depth=False
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+def build_pipeline(
+    env: str = "x86_dev",
+    config=None,
+    repository=None,
+    streamer=None,
+) -> "FlightProcessor":
+    """Build and return a fully-wired :class:`FlightProcessor`.
+
+    Parameters
+    ----------
+    env:
+        Target runtime environment.  One of ``"jetson"``, ``"x86_dev"``,
+        ``"ci"``, ``"sitl"``.
+    config:
+        Optional :class:`~gps_denied.config.AppSettings` instance.  When
+        ``None``, a fresh ``AppSettings()`` is constructed.
+    repository:
+        Optional :class:`~gps_denied.db.repository.FlightRepository`.
+        ``None`` is acceptable for smoke-tests / lifespan startup; ``deps.py``
+        swaps in a real session-scoped instance per request.
+    streamer:
+        Optional :class:`~gps_denied.pipeline.sse_streamer.SSEEventStreamer`.
+        Defaults to a fresh in-process instance when ``None``.
+
+    Returns
+    -------
+    FlightProcessor
+        Fully wired processor with all components attached.
+    """
+    # Lazy imports to avoid circular import chains at module load time.
+    from gps_denied.components.gpr.faiss_gpr import GlobalPlaceRecognition
+    from gps_denied.components.mavlink_io.pymavlink_bridge import MAVLinkBridge
+    from gps_denied.components.satellite_matcher.local_tile_loader import SatelliteDataManager
+    from gps_denied.components.satellite_matcher.metric_refinement import MetricRefinement
+    from gps_denied.components.vio.factory import create_vo_backend
+    from gps_denied.core.chunk_manager import RouteChunkManager
+    from gps_denied.core.coordinates import CoordinateTransformer
+    from gps_denied.core.factor_graph import FactorGraphOptimizer
+    from gps_denied.core.models import ModelManager
+    from gps_denied.core.recovery import FailureRecoveryCoordinator
+    from gps_denied.core.rotation import ImageRotationManager
+    from gps_denied.pipeline.orchestrator import FlightProcessor
+    from gps_denied.pipeline.sse_streamer import SSEEventStreamer
+    from gps_denied.schemas.graph import FactorGraphConfig
+
+    if config is None:
+        from gps_denied.config import AppSettings
+        config = AppSettings()
+
+    if streamer is None:
+        streamer = SSEEventStreamer()
+
+    # ------------------------------------------------------------------
+    # Env-conditional flags
+    # ------------------------------------------------------------------
+    prefer_cuvslam = env == "jetson"
+    prefer_mono_depth = env == "jetson"
+
+    # ------------------------------------------------------------------
+    # Model manager — ModelManager auto-selects TRT on Jetson
+    # ------------------------------------------------------------------
+    mm = ModelManager(engine_dir=str(config.models.weights_dir))
+
+    # ------------------------------------------------------------------
+    # Component wiring (mirrors lifespan in app.py)
+    # ------------------------------------------------------------------
+    vo = create_vo_backend(
+        model_manager=mm,
+        prefer_cuvslam=prefer_cuvslam,
+        prefer_mono_depth=prefer_mono_depth,
+    )
+    gpr = GlobalPlaceRecognition(mm)
+    metric = MetricRefinement(mm)
+    graph = FactorGraphOptimizer(FactorGraphConfig())
+    chunk_mgr = RouteChunkManager(graph)
+    recovery = FailureRecoveryCoordinator(chunk_mgr, gpr, metric)
+    rotation = ImageRotationManager(mm)
+    coord = CoordinateTransformer()
+    satellite = SatelliteDataManager(tile_dir=config.satellite.tile_dir)
+
+    # MAVLink: ci env may have no network — catch and fall back to None
+    mavlink = None
+    if env != "ci":
+        try:
+            mavlink = MAVLinkBridge(
+                connection_string=config.mavlink.connection,
+                output_hz=config.mavlink.output_hz,
+                telemetry_hz=config.mavlink.telemetry_hz,
+            )
+        except Exception as exc:
+            logger.warning("MAVLink bridge instantiation failed (env=%s): %s", env, exc)
+    else:
+        # ci: attempt anyway but tolerate failures
+        try:
+            mavlink = MAVLinkBridge(
+                connection_string=config.mavlink.connection,
+                output_hz=config.mavlink.output_hz,
+                telemetry_hz=config.mavlink.telemetry_hz,
+            )
+        except Exception as exc:
+            logger.info("MAVLink skipped in ci env: %s", exc)
+            mavlink = None
+
+    # ------------------------------------------------------------------
+    # Construct processor and attach all components
+    # ------------------------------------------------------------------
+    from gps_denied.schemas.eskf import ESKFConfig
+    eskf_config = ESKFConfig(**config.eskf.model_dump())
+
+    processor = FlightProcessor(
+        repository=repository,
+        streamer=streamer,
+        eskf_config=eskf_config,
+    )
+    processor.attach_components(
+        vo=vo,
+        gpr=gpr,
+        metric=metric,
+        graph=graph,
+        recovery=recovery,
+        chunk_mgr=chunk_mgr,
+        rotation=rotation,
+        coord=coord,
+        satellite=satellite,
+        mavlink=mavlink,
+    )
+
+    logger.info(
+        "Pipeline built: env=%s, prefer_cuvslam=%s, prefer_mono_depth=%s, mavlink=%s",
+        env, prefer_cuvslam, prefer_mono_depth,
+        config.mavlink.connection if mavlink else "disabled",
+    )
+    return processor

src/gps_denied/pipeline/image_input.py

@@ -0,0 +1,227 @@
+"""Image Input Pipeline (Component F05)."""
+
+import asyncio
+import os
+import re
+from datetime import datetime, timezone
+
+import cv2
+import numpy as np
+
+from gps_denied.schemas.image import (
+    ImageBatch,
+    ImageData,
+    ImageMetadata,
+    ProcessedBatch,
+    ProcessingStatus,
+    ValidationResult,
+)
+
+
+class QueueFullError(Exception):
+    pass
+
+class ValidationError(Exception):
+    pass
+
+
+class ImageInputPipeline:
+    """Manages ingestion, disk storage, and queuing of UAV image batches."""
+
+    def __init__(self, storage_dir: str = "image_storage", max_queue_size: int = 50):
+        self.storage_dir = storage_dir
+        # flight_id -> asyncio.Queue of ImageBatch
+        self._queues: dict[str, asyncio.Queue] = {}
+        self.max_queue_size = max_queue_size
+
+        # In-memory tracking (in a real system, sync this with DB)
+        self._status: dict[str, dict] = {}
+        # Exact sequence → filename mapping (VO-05: no substring collision)
+        self._sequence_map: dict[str, dict[int, str]] = {}
+
+    def _get_queue(self, flight_id: str) -> asyncio.Queue:
+        if flight_id not in self._queues:
+            self._queues[flight_id] = asyncio.Queue(maxsize=self.max_queue_size)
+        return self._queues[flight_id]
+
+    def _init_status(self, flight_id: str):
+        if flight_id not in self._status:
+            self._status[flight_id] = {
+                "total_images": 0,
+                "processed_images": 0,
+                "current_sequence": 1,
+            }
+
+    def validate_batch(self, batch: ImageBatch) -> ValidationResult:
+        """Validates batch integrity and sequence continuity."""
+        errors = []
+
+        num_images = len(batch.images)
+        if num_images < 1:
+            errors.append("Batch is empty")
+        elif num_images > 100:
+            errors.append("Batch too large")
+
+        if len(batch.filenames) != num_images:
+            errors.append("Mismatch between filenames and images count")
+
+        # Naming convention ADxxxxxx.jpg or similar
+        pattern = re.compile(r"^[A-Za-z0-9_-]+\.(jpg|jpeg|png)$", re.IGNORECASE)
+        for fn in batch.filenames:
+            if not pattern.match(fn):
+                errors.append(f"Invalid filename: {fn}")
+                break
+
+        if batch.start_sequence > batch.end_sequence:
+            errors.append("Start sequence greater than end sequence")
+
+        return ValidationResult(valid=len(errors) == 0, errors=errors)
+
+    def queue_batch(self, flight_id: str, batch: ImageBatch) -> bool:
+        """Queues a batch of images for processing."""
+        val = self.validate_batch(batch)
+        if not val.valid:
+            raise ValidationError(f"Batch validation failed: {val.errors}")
+
+        q = self._get_queue(flight_id)
+        if q.full():
+            raise QueueFullError(f"Queue for flight {flight_id} is full")
+
+        q.put_nowait(batch)
+
+        self._init_status(flight_id)
+        self._status[flight_id]["total_images"] += len(batch.images)
+
+        return True
+
+    async def process_next_batch(self, flight_id: str) -> ProcessedBatch | None:
+        """Dequeues and processing the next batch."""
+        q = self._get_queue(flight_id)
+        if q.empty():
+            return None
+
+        batch: ImageBatch = await q.get()
+
+        processed_images = []
+        for i, raw_bytes in enumerate(batch.images):
+            # Decode
+            nparr = np.frombuffer(raw_bytes, np.uint8)
+            img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+
+            if img is None:
+                continue  # skip corrupted
+
+            seq = batch.start_sequence + i
+            fn = batch.filenames[i]
+
+            h, w = img.shape[:2]
+            meta = ImageMetadata(
+                sequence=seq,
+                filename=fn,
+                dimensions=(w, h),
+                file_size=len(raw_bytes),
+                timestamp=datetime.now(timezone.utc),
+            )
+
+            img_data = ImageData(
+                flight_id=flight_id,
+                sequence=seq,
+                filename=fn,
+                image=img,
+                metadata=meta
+            )
+            processed_images.append(img_data)
+            # VO-05: record exact sequence→filename mapping
+            self._sequence_map.setdefault(flight_id, {})[seq] = fn
+
+        # Store to disk
+        self.store_images(flight_id, processed_images)
+
+        self._status[flight_id]["processed_images"] += len(processed_images)
+        q.task_done()
+
+        return ProcessedBatch(
+            images=processed_images,
+            batch_id=f"batch_{batch.batch_number}",
+            start_sequence=batch.start_sequence,
+            end_sequence=batch.end_sequence
+        )
+
+    def store_images(self, flight_id: str, images: list[ImageData]) -> bool:
+        """Persists images to disk."""
+        flight_dir = os.path.join(self.storage_dir, flight_id)
+        os.makedirs(flight_dir, exist_ok=True)
+
+        for img in images:
+            path = os.path.join(flight_dir, img.filename)
+            cv2.imwrite(path, img.image)
+
+        return True
+
+    def get_next_image(self, flight_id: str) -> ImageData | None:
+        """Gets the next image in sequence for processing."""
+        self._init_status(flight_id)
+        seq = self._status[flight_id]["current_sequence"]
+
+        img = self.get_image_by_sequence(flight_id, seq)
+        if img:
+            self._status[flight_id]["current_sequence"] += 1
+
+        return img
+
+    def get_image_by_sequence(self, flight_id: str, sequence: int) -> ImageData | None:
+        """Retrieves a specific image by sequence number (exact match — VO-05)."""
+        flight_dir = os.path.join(self.storage_dir, flight_id)
+        if not os.path.exists(flight_dir):
+            return None
+
+        # Prefer the exact mapping built during process_next_batch
+        fn = self._sequence_map.get(flight_id, {}).get(sequence)
+        if fn:
+            path = os.path.join(flight_dir, fn)
+            img = cv2.imread(path)
+            if img is not None:
+                h, w = img.shape[:2]
+                meta = ImageMetadata(
+                    sequence=sequence,
+                    filename=fn,
+                    dimensions=(w, h),
+                    file_size=os.path.getsize(path),
+                    timestamp=datetime.now(timezone.utc),
+                )
+                return ImageData(flight_id, sequence, fn, img, meta)
+
+        # Fallback: scan directory for exact filename patterns
+        # (handles images stored before this process started)
+        for fn in os.listdir(flight_dir):
+            base, _ = os.path.splitext(fn)
+            # Accept only if the base name ends with exactly the padded sequence number
+            if base.endswith(f"{sequence:06d}") or base == str(sequence):
+                path = os.path.join(flight_dir, fn)
+                img = cv2.imread(path)
+                if img is not None:
+                    h, w = img.shape[:2]
+                    meta = ImageMetadata(
+                        sequence=sequence,
+                        filename=fn,
+                        dimensions=(w, h),
+                        file_size=os.path.getsize(path),
+                        timestamp=datetime.now(timezone.utc),
+                    )
+                    return ImageData(flight_id, sequence, fn, img, meta)
+
+        return None
+
+    def get_processing_status(self, flight_id: str) -> ProcessingStatus:
+        self._init_status(flight_id)
+        s = self._status[flight_id]
+        q = self._get_queue(flight_id)
+
+        return ProcessingStatus(
+            flight_id=flight_id,
+            total_images=s["total_images"],
+            processed_images=s["processed_images"],
+            current_sequence=s["current_sequence"],
+            queued_batches=q.qsize(),
+            processing_rate=0.0  # mock
+        )

src/gps_denied/pipeline/orchestrator.py

@@ -0,0 +1,599 @@
+"""Core Flight Processor — Full Processing Pipeline (Stage 10).
+
+Orchestrates: ImageInputPipeline → VO → MetricRefinement → FactorGraph → SSE.
+State Machine: NORMAL → LOST → RECOVERY → NORMAL.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from enum import Enum
+from typing import Optional
+
+import numpy as np
+
+from gps_denied.core.eskf import ESKF
+from gps_denied.pipeline.image_input import ImageInputPipeline
+from gps_denied.pipeline.result_manager import ResultManager
+from gps_denied.pipeline.sse_streamer import SSEEventStreamer
+from gps_denied.db.repository import FlightRepository
+from gps_denied.schemas import CameraParameters, GPSPoint
+from gps_denied.schemas.flight import (
+    BatchMetadata,
+    BatchResponse,
+    BatchUpdateResponse,
+    DeleteResponse,
+    FlightCreateRequest,
+    FlightDetailResponse,
+    FlightResponse,
+    FlightStatusResponse,
+    ObjectGPSResponse,
+    UpdateResponse,
+    UserFixRequest,
+    UserFixResponse,
+    Waypoint,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# State Machine
+# ---------------------------------------------------------------------------
+class TrackingState(str, Enum):
+    """Processing state for a flight."""
+    NORMAL = "normal"
+    LOST = "lost"
+    RECOVERY = "recovery"
+
+
+class FrameResult:
+    """Intermediate result of processing a single frame."""
+
+    def __init__(self, frame_id: int):
+        self.frame_id = frame_id
+        self.gps: Optional[GPSPoint] = None
+        self.confidence: float = 0.0
+        self.tracking_state: TrackingState = TrackingState.NORMAL
+        self.vo_success: bool = False
+        self.alignment_success: bool = False
+
+
+# ---------------------------------------------------------------------------
+# FlightProcessor
+# ---------------------------------------------------------------------------
+class FlightProcessor:
+    """Manages business logic, background processing, and frame orchestration."""
+
+    def __init__(
+        self,
+        repository: FlightRepository,
+        streamer: SSEEventStreamer,
+        eskf_config=None,
+    ) -> None:
+        self.repository = repository
+        self.streamer = streamer
+        self.result_manager = ResultManager(repository, streamer)
+        self.pipeline = ImageInputPipeline(storage_dir=".image_storage", max_queue_size=50)
+        self._eskf_config = eskf_config  # ESKFConfig or None → default
+
+        # Per-flight processing state
+        self._flight_states: dict[str, TrackingState] = {}
+        self._prev_images: dict[str, np.ndarray] = {}  # previous frame cache
+        self._flight_cameras: dict[str, CameraParameters] = {}  # per-flight camera
+        self._altitudes: dict[str, float] = {}          # per-flight altitude (m)
+        self._failure_counts: dict[str, int] = {}       # per-flight consecutive failure counter
+
+        # Per-flight ESKF instances (PIPE-01/07)
+        self._eskf: dict[str, ESKF] = {}
+
+        # Lazy-initialised component references (set via `attach_components`)
+        self._vo = None           # ISequentialVisualOdometry
+        self._gpr = None          # IGlobalPlaceRecognition
+        self._metric = None       # IMetricRefinement
+        self._graph = None        # IFactorGraphOptimizer
+        self._recovery = None     # IFailureRecoveryCoordinator
+        self._chunk_mgr = None    # IRouteChunkManager
+        self._rotation = None     # ImageRotationManager
+        self._satellite = None    # SatelliteDataManager (PIPE-02)
+        self._coord = None        # CoordinateTransformer (PIPE-02/06)
+        self._mavlink = None      # MAVLinkBridge (PIPE-07)
+
+    # ------ Dependency injection for core components ---------
+    def attach_components(
+        self,
+        vo=None,
+        gpr=None,
+        metric=None,
+        graph=None,
+        recovery=None,
+        chunk_mgr=None,
+        rotation=None,
+        satellite=None,
+        coord=None,
+        mavlink=None,
+    ):
+        """Attach pipeline components after construction (avoids circular deps)."""
+        self._vo = vo
+        self._gpr = gpr
+        self._metric = metric
+        self._graph = graph
+        self._recovery = recovery
+        self._chunk_mgr = chunk_mgr
+        self._rotation = rotation
+        self._satellite = satellite   # PIPE-02: SatelliteDataManager
+        self._coord = coord           # PIPE-02/06: CoordinateTransformer
+        self._mavlink = mavlink       # PIPE-07: MAVLinkBridge
+
+    # ------ ESKF lifecycle helpers ----------------------------
+    def _init_eskf_for_flight(
+        self, flight_id: str, start_gps: GPSPoint, altitude: float
+    ) -> None:
+        """Create and initialize a per-flight ESKF instance."""
+        if flight_id in self._eskf:
+            return
+        eskf = ESKF(config=self._eskf_config)
+        if self._coord:
+            try:
+                e, n, _ = self._coord.gps_to_enu(flight_id, start_gps)
+                eskf.initialize(np.array([e, n, altitude]), time.time())
+            except Exception:
+                eskf.initialize(np.zeros(3), time.time())
+        else:
+            eskf.initialize(np.zeros(3), time.time())
+        self._eskf[flight_id] = eskf
+
+    def _eskf_to_gps(self, flight_id: str, eskf: ESKF) -> Optional[GPSPoint]:
+        """Convert current ESKF ENU position to WGS84 GPS."""
+        if not eskf.initialized or self._coord is None:
+            return None
+        try:
+            pos = eskf.position
+            return self._coord.enu_to_gps(flight_id, (float(pos[0]), float(pos[1]), float(pos[2])))
+        except Exception:
+            return None
+
+    # =========================================================
+    # process_frame — central orchestration
+    # =========================================================
+    async def process_frame(
+        self,
+        flight_id: str,
+        frame_id: int,
+        image: np.ndarray,
+    ) -> FrameResult:
+        """
+        Process a single UAV frame through the full pipeline.
+
+        State transitions:
+            NORMAL  — VO succeeds → ESKF VO update, attempt satellite fix
+            LOST    — VO failed → create new chunk, enter RECOVERY
+            RECOVERY— try GPR + MetricRefinement → if anchored, merge & return to NORMAL
+
+        PIPE-01: VO result → eskf.update_vo → satellite match → eskf.update_satellite → MAVLink GPS_INPUT
+        PIPE-02: SatelliteDataManager + CoordinateTransformer wired for tile selection
+        PIPE-04: Consecutive failure counter wired to FailureRecoveryCoordinator
+        PIPE-05: ImageRotationManager initialised on first frame
+        PIPE-07: ESKF confidence → MAVLink fix_type via bridge.update_state
+        """
+        result = FrameResult(frame_id)
+        state = self._flight_states.get(flight_id, TrackingState.NORMAL)
+        eskf = self._eskf.get(flight_id)
+
+        _default_cam = CameraParameters(
+            focal_length=4.5, sensor_width=6.17, sensor_height=4.55,
+            resolution_width=640, resolution_height=480,
+        )
+
+        # ---- PIPE-05: Initialise heading tracking on first frame ----
+        if self._rotation and frame_id == 0:
+            self._rotation.requires_rotation_sweep(flight_id)  # seeds HeadingHistory
+
+        # ---- 1. Visual Odometry (frame-to-frame) ----
+        vo_ok = False
+        if self._vo and flight_id in self._prev_images:
+            try:
+                cam = self._flight_cameras.get(flight_id, _default_cam)
+                rel_pose = self._vo.compute_relative_pose(
+                    self._prev_images[flight_id], image, cam
+                )
+                if rel_pose and rel_pose.tracking_good:
+                    vo_ok = True
+                    result.vo_success = True
+
+                    if self._graph:
+                        self._graph.add_relative_factor(
+                            flight_id, frame_id - 1, frame_id, rel_pose, np.eye(6)
+                        )
+
+                    # PIPE-01: Feed VO relative displacement into ESKF
+                    if eskf and eskf.initialized:
+                        now = time.time()
+                        dt_vo = max(0.01, now - (eskf.last_timestamp or now))
+                        eskf.update_vo(rel_pose.translation, dt_vo)
+            except Exception as exc:
+                logger.warning("VO failed for frame %d: %s", frame_id, exc)
+
+        # Store current image for next frame
+        self._prev_images[flight_id] = image
+
+        # ---- PIPE-04: Consecutive failure counter ----
+        if not vo_ok and frame_id > 0:
+            self._failure_counts[flight_id] = self._failure_counts.get(flight_id, 0) + 1
+        else:
+            self._failure_counts[flight_id] = 0
+
+        # ---- 2. State Machine transitions ----
+        if state == TrackingState.NORMAL:
+            if not vo_ok and frame_id > 0:
+                state = TrackingState.LOST
+                logger.info("Flight %s → LOST at frame %d", flight_id, frame_id)
+                if self._recovery:
+                    self._recovery.handle_tracking_lost(flight_id, frame_id)
+
+        if state == TrackingState.LOST:
+            state = TrackingState.RECOVERY
+
+        if state == TrackingState.RECOVERY:
+            recovered = False
+            if self._recovery and self._chunk_mgr:
+                active_chunk = self._chunk_mgr.get_active_chunk(flight_id)
+                if active_chunk:
+                    recovered = self._recovery.process_chunk_recovery(
+                        flight_id, active_chunk.chunk_id, [image]
+                    )
+            if recovered:
+                state = TrackingState.NORMAL
+                result.alignment_success = True
+                # PIPE-04: Reset failure count on successful recovery
+                self._failure_counts[flight_id] = 0
+                logger.info("Flight %s recovered → NORMAL at frame %d", flight_id, frame_id)
+
+        # ---- 3. Satellite position fix (PIPE-01/02) ----
+        if state == TrackingState.NORMAL and self._metric:
+            sat_tile: Optional[np.ndarray] = None
+            tile_bounds = None
+
+            # PIPE-02: Prefer real SatelliteDataManager tiles (ESKF ±3σ selection)
+            if self._satellite and eskf and eskf.initialized:
+                gps_est = self._eskf_to_gps(flight_id, eskf)
+                if gps_est:
+                    cov = eskf.covariance
+                    sigma_h = float(
+                        np.sqrt(np.trace(cov[0:3, 0:3]) / 3.0)
+                    ) if cov is not None else 30.0
+                    sigma_h = max(sigma_h, 5.0)
+                    try:
+                        tile_result = await asyncio.get_event_loop().run_in_executor(
+                            None,
+                            self._satellite.fetch_tiles_for_position,
+                            gps_est, sigma_h, 18,
+                        )
+                        if tile_result:
+                            sat_tile, tile_bounds = tile_result
+                    except Exception as exc:
+                        logger.debug("Satellite tile fetch failed: %s", exc)
+
+            # Fallback: GPR candidate tile (mock image, real bounds)
+            if sat_tile is None and self._gpr:
+                try:
+                    candidates = self._gpr.retrieve_candidate_tiles(image, top_k=1)
+                    if candidates:
+                        sat_tile = np.zeros((256, 256, 3), dtype=np.uint8)
+                        tile_bounds = candidates[0].bounds
+                except Exception as exc:
+                    logger.debug("GPR tile fallback failed: %s", exc)
+
+            if sat_tile is not None and tile_bounds is not None:
+                try:
+                    align = self._metric.align_to_satellite(image, sat_tile, tile_bounds)
+                    if align and align.matched:
+                        result.gps = align.gps_center
+                        result.confidence = align.confidence
+                        result.alignment_success = True
+
+                        if self._graph:
+                            self._graph.add_absolute_factor(
+                                flight_id, frame_id,
+                                align.gps_center, np.eye(6),
+                                is_user_anchor=False,
+                            )
+
+                        # PIPE-01: ESKF satellite update — noise from RANSAC confidence
+                        if eskf and eskf.initialized and self._coord:
+                            try:
+                                e, n, _ = self._coord.gps_to_enu(flight_id, align.gps_center)
+                                alt = self._altitudes.get(flight_id, 100.0)
+                                pos_enu = np.array([e, n, alt])
+                                noise_m = 5.0 + 15.0 * (1.0 - float(align.confidence))
+                                eskf.update_satellite(pos_enu, noise_m)
+                            except Exception as exc:
+                                logger.debug("ESKF satellite update failed: %s", exc)
+                except Exception as exc:
+                    logger.warning("Metric alignment failed at frame %d: %s", frame_id, exc)
+
+        # ---- 4. Graph optimization (incremental) ----
+        if self._graph:
+            opt_result = self._graph.optimize(flight_id, iterations=5)
+            logger.debug(
+                "Optimization: converged=%s, error=%.4f",
+                opt_result.converged, opt_result.final_error,
+            )
+
+        # ---- PIPE-07: Push ESKF state → MAVLink GPS_INPUT ----
+        if self._mavlink and eskf and eskf.initialized:
+            try:
+                eskf_state = eskf.get_state()
+                alt = self._altitudes.get(flight_id, 100.0)
+                self._mavlink.update_state(eskf_state, altitude_m=alt)
+            except Exception as exc:
+                logger.debug("MAVLink state push failed: %s", exc)
+
+        # ---- 5. Publish via SSE ----
+        result.tracking_state = state
+        self._flight_states[flight_id] = state
+        await self._publish_frame_result(flight_id, result)
+        return result
+
+    async def _publish_frame_result(self, flight_id: str, result: FrameResult):
+        """Emit SSE event for processed frame."""
+        event_data = {
+            "frame_id": result.frame_id,
+            "tracking_state": result.tracking_state.value,
+            "vo_success": result.vo_success,
+            "alignment_success": result.alignment_success,
+            "confidence": result.confidence,
+        }
+        if result.gps:
+            event_data["lat"] = result.gps.lat
+            event_data["lon"] = result.gps.lon
+
+        await self.streamer.push_event(
+            flight_id, event_type="frame_result", data=event_data
+        )
+
+    # =========================================================
+    # Existing CRUD / REST helpers (unchanged from Stage 3-4)
+    # =========================================================
+    async def create_flight(self, req: FlightCreateRequest) -> FlightResponse:
+        flight = await self.repository.insert_flight(
+            name=req.name,
+            description=req.description,
+            start_lat=req.start_gps.lat,
+            start_lon=req.start_gps.lon,
+            altitude=req.altitude,
+            camera_params=req.camera_params.model_dump(),
+        )
+        # P0#2: Store camera params for process_frame VO calls
+        self._flight_cameras[flight.id] = req.camera_params
+
+        for poly in req.geofences.polygons:
+            await self.repository.insert_geofence(
+                flight.id,
+                nw_lat=poly.north_west.lat,
+                nw_lon=poly.north_west.lon,
+                se_lat=poly.south_east.lat,
+                se_lon=poly.south_east.lon,
+            )
+        for w in req.rough_waypoints:
+            await self.repository.insert_waypoint(flight.id, lat=w.lat, lon=w.lon)
+
+        # Store per-flight altitude for ESKF/pixel projection
+        self._altitudes[flight.id] = req.altitude or 100.0
+
+        # PIPE-02: Set ENU origin and initialise ESKF for this flight
+        if self._coord:
+            self._coord.set_enu_origin(flight.id, req.start_gps)
+        self._init_eskf_for_flight(flight.id, req.start_gps, req.altitude or 100.0)
+
+        # Start MAVLink bridge for this flight (origin required for GPS_INPUT)
+        if self._mavlink and not self._mavlink._running:
+            try:
+                asyncio.create_task(self._mavlink.start(req.start_gps))
+            except Exception as exc:
+                logger.warning("MAVLink bridge start failed: %s", exc)
+
+        return FlightResponse(
+            flight_id=flight.id,
+            status="prefetching",
+            message="Flight created and prefetching started.",
+            created_at=flight.created_at,
+        )
+
+    async def get_flight(self, flight_id: str) -> FlightDetailResponse | None:
+        flight = await self.repository.get_flight(flight_id)
+        if not flight:
+            return None
+        wps = await self.repository.get_waypoints(flight_id)
+        state = await self.repository.load_flight_state(flight_id)
+
+        waypoints = [
+            Waypoint(
+                id=w.id,
+                lat=w.lat,
+                lon=w.lon,
+                altitude=w.altitude,
+                confidence=w.confidence,
+                timestamp=w.timestamp,
+                refined=w.refined,
+            )
+            for w in wps
+        ]
+
+        status = state.status if state else "unknown"
+        frames_processed = state.frames_processed if state else 0
+        frames_total = state.frames_total if state else 0
+
+        from gps_denied.schemas import Geofences
+
+        return FlightDetailResponse(
+            flight_id=flight.id,
+            name=flight.name,
+            description=flight.description,
+            start_gps=GPSPoint(lat=flight.start_lat, lon=flight.start_lon),
+            waypoints=waypoints,
+            geofences=Geofences(polygons=[]),
+            camera_params=flight.camera_params,
+            altitude=flight.altitude,
+            status=status,
+            frames_processed=frames_processed,
+            frames_total=frames_total,
+            created_at=flight.created_at,
+            updated_at=flight.updated_at,
+        )
+
+    async def delete_flight(self, flight_id: str) -> DeleteResponse:
+        deleted = await self.repository.delete_flight(flight_id)
+        # P0#1: Cleanup in-memory state to prevent memory leaks
+        self._cleanup_flight(flight_id)
+        return DeleteResponse(deleted=deleted, flight_id=flight_id)
+
+    def _cleanup_flight(self, flight_id: str) -> None:
+        """Remove all in-memory state for a flight (prevents memory leaks)."""
+        self._prev_images.pop(flight_id, None)
+        self._flight_states.pop(flight_id, None)
+        self._flight_cameras.pop(flight_id, None)
+        self._altitudes.pop(flight_id, None)
+        self._failure_counts.pop(flight_id, None)
+        self._eskf.pop(flight_id, None)
+        if self._graph:
+            self._graph.delete_flight_graph(flight_id)
+
+    async def update_waypoint(
+        self, flight_id: str, waypoint_id: str, waypoint: Waypoint
+    ) -> UpdateResponse:
+        ok = await self.repository.update_waypoint(
+            flight_id,
+            waypoint_id,
+            lat=waypoint.lat,
+            lon=waypoint.lon,
+            altitude=waypoint.altitude,
+            confidence=waypoint.confidence,
+            refined=waypoint.refined,
+        )
+        return UpdateResponse(updated=ok, waypoint_id=waypoint_id)
+
+    async def batch_update_waypoints(
+        self, flight_id: str, waypoints: list[Waypoint]
+    ) -> BatchUpdateResponse:
+        failed = []
+        updated = 0
+        for wp in waypoints:
+            ok = await self.repository.update_waypoint(
+                flight_id,
+                wp.id,
+                lat=wp.lat,
+                lon=wp.lon,
+                altitude=wp.altitude,
+                confidence=wp.confidence,
+                refined=wp.refined,
+            )
+            if ok:
+                updated += 1
+            else:
+                failed.append(wp.id)
+        return BatchUpdateResponse(
+            success=(len(failed) == 0), updated_count=updated, failed_ids=failed
+        )
+
+    async def queue_images(
+        self, flight_id: str, metadata: BatchMetadata, file_count: int
+    ) -> BatchResponse:
+        state = await self.repository.load_flight_state(flight_id)
+        if state:
+            total = state.frames_total + file_count
+            await self.repository.save_flight_state(
+                flight_id, frames_total=total, status="processing"
+            )
+
+        next_seq = metadata.end_sequence + 1
+        seqs = list(range(metadata.start_sequence, metadata.end_sequence + 1))
+        return BatchResponse(
+            accepted=True,
+            sequences=seqs,
+            next_expected=next_seq,
+            message=f"Queued {file_count} images.",
+        )
+
+    async def handle_user_fix(
+        self, flight_id: str, req: UserFixRequest
+    ) -> UserFixResponse:
+        await self.repository.save_flight_state(
+            flight_id, blocked=False, status="processing"
+        )
+
+        # Inject operator position into ESKF with high uncertainty (500m)
+        eskf = self._eskf.get(flight_id)
+        if eskf and eskf.initialized and self._coord:
+            try:
+                e, n, _ = self._coord.gps_to_enu(flight_id, req.satellite_gps)
+                alt = self._altitudes.get(flight_id, 100.0)
+                eskf.update_satellite(np.array([e, n, alt]), noise_meters=500.0)
+                self._failure_counts[flight_id] = 0
+                logger.info("User fix applied for %s: %s", flight_id, req.satellite_gps)
+            except Exception as exc:
+                logger.warning("User fix ESKF injection failed: %s", exc)
+
+        return UserFixResponse(
+            accepted=True, processing_resumed=True, message="Fix applied."
+        )
+
+    async def get_flight_status(self, flight_id: str) -> FlightStatusResponse | None:
+        state = await self.repository.load_flight_state(flight_id)
+        if not state:
+            return None
+        return FlightStatusResponse(
+            status=state.status,
+            frames_processed=state.frames_processed,
+            frames_total=state.frames_total,
+            current_frame=state.current_frame,
+            current_heading=None,
+            blocked=state.blocked,
+            search_grid_size=state.search_grid_size,
+            created_at=state.created_at,
+            updated_at=state.updated_at,
+        )
+
+    async def convert_object_to_gps(
+        self, flight_id: str, frame_id: int, pixel: tuple[float, float]
+    ) -> ObjectGPSResponse:
+        # PIPE-06: Use real CoordinateTransformer + ESKF pose for ray-ground projection
+        gps: Optional[GPSPoint] = None
+        eskf = self._eskf.get(flight_id)
+        if self._coord and eskf and eskf.initialized:
+            pos = eskf.position
+            quat = eskf.quaternion
+            cam = self._flight_cameras.get(flight_id, CameraParameters(
+                focal_length=4.5, sensor_width=6.17, sensor_height=4.55,
+                resolution_width=640, resolution_height=480,
+            ))
+            alt = self._altitudes.get(flight_id, 100.0)
+            try:
+                gps = self._coord.pixel_to_gps(
+                    flight_id,
+                    pixel,
+                    frame_pose={"position": pos},
+                    camera_params=cam,
+                    altitude=float(alt),
+                    quaternion=quat,
+                )
+            except Exception as exc:
+                logger.debug("pixel_to_gps failed: %s", exc)
+
+        # Fallback: return ESKF position projected to ground (no pixel shift)
+        if gps is None and eskf:
+            gps = self._eskf_to_gps(flight_id, eskf)
+
+        return ObjectGPSResponse(
+            gps=gps or GPSPoint(lat=0.0, lon=0.0),
+            accuracy_meters=5.0,
+            frame_id=frame_id,
+            pixel=pixel,
+        )
+
+    async def stream_events(self, flight_id: str, client_id: str):
+        """Async generator for SSE stream."""
+        async for event in self.streamer.stream_generator(flight_id, client_id):
+            yield event

src/gps_denied/pipeline/result_manager.py

@@ -0,0 +1,73 @@
+"""Result Manager (Component F14)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from gps_denied.pipeline.sse_streamer import SSEEventStreamer
+from gps_denied.db.repository import FlightRepository
+from gps_denied.schemas import GPSPoint
+from gps_denied.schemas.events import FrameProcessedEvent
+
+
+class ResultManager:
+    """Result consistency and publishing."""
+
+    def __init__(self, repo: FlightRepository, sse: SSEEventStreamer) -> None:
+        self.repo = repo
+        self.sse = sse
+
+    async def update_frame_result(
+        self,
+        flight_id: str,
+        frame_id: int,
+        gps_lat: float,
+        gps_lon: float,
+        altitude: float,
+        heading: float,
+        confidence: float,
+        timestamp: datetime,
+        refined: bool = False,
+    ) -> bool:
+        """Atomic DB update + SSE event publish."""
+
+        # 1. Update DB (in the repository these are auto-committing via flush,
+        # but normally F03 would wrap in a single transaction).
+        await self.repo.save_frame_result(
+            flight_id,
+            frame_id=frame_id,
+            gps_lat=gps_lat,
+            gps_lon=gps_lon,
+            altitude=altitude,
+            heading=heading,
+            confidence=confidence,
+            refined=refined,
+        )
+
+        # Wait, the spec also wants Waypoints to be updated.
+        # But image frames != waypoints. Waypoints are the planned route.
+        # Actually in the spec it says: "Updates waypoint in waypoints table."
+        # This implies updating the closest waypoint or a generated waypoint path.
+        # We will follow the simplest form for now: update the waypoint if there is one corresponding.
+        # Let's say we update a waypoint with id "wp_{frame_id}" for now if we know how they map,
+        # or we just skip unless specified.
+
+        # 2. Trigger SSE event
+        evt = FrameProcessedEvent(
+            frame_id=frame_id,
+            gps=GPSPoint(lat=gps_lat, lon=gps_lon),
+            altitude=altitude,
+            confidence=confidence,
+            heading=heading,
+            timestamp=timestamp,
+        )
+        if refined:
+            self.sse.send_refinement(flight_id, evt)
+        else:
+            self.sse.send_frame_result(flight_id, evt)
+
+        return True
+
+    async def publish_waypoint_update(self, flight_id: str, frame_id: int) -> bool:
+        # Just delegates to SSE for waypoint updates, which is basically the frame result for UI
+        pass

src/gps_denied/pipeline/sse_streamer.py

@@ -0,0 +1,164 @@
+"""SSE Event Streamer (Component F15)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections import defaultdict
+
+from gps_denied.schemas.events import (
+    FlightCompletedEvent,
+    FrameProcessedEvent,
+    SearchExpandedEvent,
+    SSEEventType,
+    SSEMessage,
+    UserInputNeededEvent,
+)
+
+
+class SSEEventStreamer:
+    """Manages real-time SSE connections and event broadcasting."""
+
+    def __init__(self) -> None:
+        # Map: flight_id -> Dict[client_id, asyncio.Queue]
+        self._streams: dict[str, dict[str, asyncio.Queue[SSEMessage | None]]] = defaultdict(dict)
+
+    def create_stream(self, flight_id: str, client_id: str) -> asyncio.Queue[SSEMessage | None]:
+        """Create a new event queue for a client."""
+        q: asyncio.Queue[SSEMessage | None] = asyncio.Queue()
+        self._streams[flight_id][client_id] = q
+        return q
+
+    def close_stream(self, flight_id: str, client_id: str) -> None:
+        """Close a client stream by putting a sentinel and removing the queue."""
+        if flight_id in self._streams and client_id in self._streams[flight_id]:
+            q = self._streams[flight_id].pop(client_id)
+            if not self._streams[flight_id]:
+                del self._streams[flight_id]
+            # Put None to signal generator exit
+            try:
+                q.put_nowait(None)
+            except asyncio.QueueFull:
+                pass
+
+    def get_active_connections(self, flight_id: str) -> int:
+        return len(self._streams.get(flight_id, {}))
+
+    def _broadcast(self, flight_id: str, msg: SSEMessage) -> bool:
+        """Broadcast a message to all clients subscribed to flight_id."""
+        if flight_id not in self._streams or not self._streams[flight_id]:
+            return False
+
+        for q in self._streams[flight_id].values():
+            try:
+                q.put_nowait(msg)
+            except asyncio.QueueFull:
+                pass  # Drop if queue is full rather than blocking
+        return True
+
+    # ── Business Event Senders ────────────────────────────────────────────────
+
+    def send_frame_result(self, flight_id: str, event_data: FrameProcessedEvent) -> bool:
+        msg = SSEMessage(
+            event=SSEEventType.FRAME_PROCESSED,
+            data=event_data.model_dump(mode="json"),
+            id=f"frame_{event_data.frame_id}",
+        )
+        return self._broadcast(flight_id, msg)
+
+    def send_refinement(self, flight_id: str, event_data: FrameProcessedEvent) -> bool:
+        msg = SSEMessage(
+            event=SSEEventType.FRAME_REFINED,
+            data=event_data.model_dump(mode="json"),
+            id=f"refine_{event_data.frame_id}",
+        )
+        return self._broadcast(flight_id, msg)
+
+    def send_search_progress(self, flight_id: str, event_data: SearchExpandedEvent) -> bool:
+        msg = SSEMessage(
+            event=SSEEventType.SEARCH_EXPANDED,
+            data=event_data.model_dump(mode="json"),
+        )
+        return self._broadcast(flight_id, msg)
+
+    def send_user_input_request(self, flight_id: str, event_data: UserInputNeededEvent) -> bool:
+        msg = SSEMessage(
+            event=SSEEventType.USER_INPUT_NEEDED,
+            data=event_data.model_dump(mode="json"),
+        )
+        return self._broadcast(flight_id, msg)
+
+    def send_flight_completed(self, flight_id: str, event_data: FlightCompletedEvent) -> bool:
+        msg = SSEMessage(
+            event=SSEEventType.FLIGHT_COMPLETED,
+            data=event_data.model_dump(mode="json"),
+        )
+        return self._broadcast(flight_id, msg)
+
+    def send_heartbeat(self, flight_id: str) -> bool:
+        # sse_starlette uses empty string or comment for heartbeat,
+        # but we can just send an SSEMessage object that parses as empty event
+        if flight_id not in self._streams:
+            return False
+
+        # Manually sending a comment via the generator is tricky with strict SSEMessage schema
+        # but we'll handle this in the stream generator directly
+        return True
+
+    # ── Generic event dispatcher (used by processor.process_frame) ──────────
+
+    async def push_event(self, flight_id: str, event_type: str, data: dict) -> None:
+        """Dispatch a generic event to all clients for a flight.
+
+        Maps event_type strings to typed SSE events:
+          "frame_result"  → FrameProcessedEvent
+          "refinement"    → FrameProcessedEvent (refined)
+          Other           → raw broadcast via SSEMessage
+        """
+        if event_type == "frame_result":
+            evt = FrameProcessedEvent(**data) if not isinstance(data, FrameProcessedEvent) else data
+            self.send_frame_result(flight_id, evt)
+        elif event_type == "refinement":
+            evt = FrameProcessedEvent(**data) if not isinstance(data, FrameProcessedEvent) else data
+            self.send_refinement(flight_id, evt)
+        else:
+            msg = SSEMessage(
+                event=SSEEventType.FRAME_PROCESSED,
+                data=data,
+                id=str(data.get("frame_id", "")),
+            )
+            self._broadcast(flight_id, msg)
+
+    # ── Stream Generator ──────────────────────────────────────────────────────
+
+    async def stream_generator(self, flight_id: str, client_id: str):
+        """Yields dicts for sse_starlette EventSourceResponse."""
+        q = self.create_stream(flight_id, client_id)
+
+        # Send an immediate connection accepted ping
+        yield {"event": "connected", "data": "connected"}
+
+        try:
+            while True:
+                # Wait for next event or send heartbeat every 15s
+                try:
+                    msg = await asyncio.wait_for(q.get(), timeout=15.0)
+                    if msg is None:
+                        # Sentinel for clean shutdown
+                        break
+
+                    # Yield dict format for sse_starlette
+                    yield {
+                        "event": msg.event.value,
+                        "id": msg.id if msg.id else "",
+                        "data": json.dumps(msg.data)
+                    }
+
+                except asyncio.TimeoutError:
+                    # Heartbeat format for sse_starlette (empty string generates a comment)
+                    yield {"event": "heartbeat", "data": "ping"}
+
+        except asyncio.CancelledError:
+            pass  # Client disconnected
+        finally:
+            self.close_stream(flight_id, client_id)

src/gps_denied/schemas/eskf.py

@@ -1,9 +1,16 @@
-"""Error-State Kalman Filter schemas."""
+"""Error-State Kalman Filter schemas.
+
+Phase 1 shim — hot-path types `IMUSample` (legacy: `IMUMeasurement`) and
+`ESKFState` live in `gps_denied.hot_types`. `ConfidenceTier` (enum) and
+`ESKFConfig` (Pydantic config) stay here as boundary types.
+
+`ConfidenceTier` is defined BEFORE the hot_types re-imports because
+`hot_types.eskf_state` imports `ConfidenceTier` from this module — load
+order matters to avoid a circular import.
+"""
 
 from enum import Enum
-from typing import Optional
 
-import numpy as np
 from pydantic import BaseModel
 
 
@@ -15,15 +22,6 @@ class ConfidenceTier(str, Enum):
     FAILED = "FAILED"   # 3+ consecutive total failures
 
 
-class IMUMeasurement(BaseModel):
-    """Single IMU reading from flight controller."""
-    model_config = {"arbitrary_types_allowed": True}
-
-    accel: np.ndarray  # (3,) m/s^2 in body frame
-    gyro: np.ndarray   # (3,) rad/s in body frame
-    timestamp: float   # seconds since epoch
-
-
 class ESKFConfig(BaseModel):
     """ESKF tuning parameters."""
 
@@ -55,17 +53,22 @@ class ESKFConfig(BaseModel):
     mahalanobis_threshold: float = 16.27   # chi2(3, 0.99999) ≈ 5-sigma gate
 
 
-class ESKFState(BaseModel):
-    """Full ESKF nominal state snapshot."""
-    model_config = {"arbitrary_types_allowed": True}
+# Hot-path types — re-exported from gps_denied.hot_types (Plan 01-01).
+# Tests and existing consumers continue to import from this path; the
+# underlying type changed from a Pydantic BaseModel to a frozen dataclass.
+# These imports MUST come AFTER `ConfidenceTier` is defined above —
+# `hot_types.eskf_state` imports `ConfidenceTier` from this module.
+from gps_denied.hot_types.eskf_state import ESKFState  # noqa: E402, F401
+from gps_denied.hot_types.imu_sample import IMUSample  # noqa: E402, F401
 
-    position: np.ndarray       # (3,) ENU meters from origin (East, North, Up)
-    velocity: np.ndarray       # (3,) ENU m/s
-    quaternion: np.ndarray     # (4,) [w, x, y, z] body-to-ENU
-    accel_bias: np.ndarray     # (3,) m/s^2
-    gyro_bias: np.ndarray      # (3,) rad/s
-    covariance: np.ndarray     # (15, 15)
-    timestamp: float           # seconds since epoch
-    confidence: ConfidenceTier
-    last_satellite_time: Optional[float] = None
-    last_vo_time: Optional[float] = None
+# Legacy alias preserved until Phase 2 test taxonomy reshuffle.
+IMUMeasurement = IMUSample
+
+
+__all__ = [
+    "ConfidenceTier",
+    "ESKFConfig",
+    "ESKFState",
+    "IMUMeasurement",
+    "IMUSample",
+]

src/gps_denied/schemas/metric.py

@@ -1,46 +1,17 @@
-"""Metric Refinement schemas (Component F09)."""
+"""Metric Refinement schemas (Component F09).
 
+Phase 1 shim — hot-path types `AlignmentResult`, `ChunkAlignmentResult`,
+`Sim3Transform` live in `gps_denied.hot_types.alignment_result`.
+`LiteSAMConfig` (config) stays here as a Pydantic boundary type.
+"""
 
-import numpy as np
 from pydantic import BaseModel
 
-from gps_denied.schemas import GPSPoint
-
-
-class AlignmentResult(BaseModel):
-    """Result of aligning a UAV image to a single satellite tile."""
-    model_config = {"arbitrary_types_allowed": True}
-
-    matched: bool
-    homography: np.ndarray  # (3, 3)
-    gps_center: GPSPoint
-    confidence: float
-    inlier_count: int
-    total_correspondences: int
-    reprojection_error: float  # Mean error in pixels
-
-
-class Sim3Transform(BaseModel):
-    """Sim(3) transformation: scale, rotation, translation."""
-    model_config = {"arbitrary_types_allowed": True}
-
-    translation: np.ndarray  # (3,)
-    rotation: np.ndarray  # (3, 3) rotation matrix
-    scale: float
-
-
-class ChunkAlignmentResult(BaseModel):
-    """Result of aligning a chunk array of UAV images to a satellite tile."""
-    model_config = {"arbitrary_types_allowed": True}
-
-    matched: bool
-    chunk_id: str
-    chunk_center_gps: GPSPoint
-    rotation_angle: float
-    confidence: float
-    inlier_count: int
-    transform: Sim3Transform
-    reprojection_error: float
+from gps_denied.hot_types.alignment_result import (  # noqa: F401
+    AlignmentResult,
+    ChunkAlignmentResult,
+    Sim3Transform,
+)
 
 
 class LiteSAMConfig(BaseModel):
@@ -51,3 +22,11 @@ class LiteSAMConfig(BaseModel):
     max_reprojection_error: float = 2.0  # pixels
     multi_scale_levels: int = 3
     chunk_min_inliers: int = 30
+
+
+__all__ = [
+    "AlignmentResult",
+    "ChunkAlignmentResult",
+    "LiteSAMConfig",
+    "Sim3Transform",
+]

src/gps_denied/schemas/rotation.py

@@ -1,24 +1,16 @@
-"""Rotation schemas (Component F06)."""
+"""Rotation schemas (Component F06).
+
+Phase 1 shim — hot-path `RotationResult` lives in
+`gps_denied.hot_types.rotation_result`. `HeadingHistory` (mutable
+bookkeeping) and `RotationConfig` (config) stay here as Pydantic.
+"""
 
 from datetime import datetime
 from typing import Optional
 
-import numpy as np
 from pydantic import BaseModel
 
-
-class RotationResult(BaseModel):
-    """Result of a rotation sweep alignment."""
-    matched: bool
-    initial_angle: float
-    precise_angle: float
-    confidence: float
-    # We will exclude np.ndarray from BaseModel to avoid validation issues,
-    # but store it as an attribute if needed or use arbitrary_types_allowed.
-
-    model_config = {"arbitrary_types_allowed": True}
-    homography: Optional[np.ndarray] = None
-    inlier_count: int = 0
+from gps_denied.hot_types.rotation_result import RotationResult  # noqa: F401
 
 
 class HeadingHistory(BaseModel):
@@ -36,3 +28,10 @@ class RotationConfig(BaseModel):
     sharp_turn_threshold: float = 45.0
     confidence_threshold: float = 0.7
     history_size: int = 10
+
+
+__all__ = [
+    "HeadingHistory",
+    "RotationConfig",
+    "RotationResult",
+]

src/gps_denied/schemas/satellite.py

@@ -1,22 +1,17 @@
-"""Satellite domain schemas."""
+"""Satellite domain schemas.
 
-from pydantic import BaseModel
+Phase 1 shim — `TileCoords`, `TileBounds`, and the Phase-3 placeholder
+`SatelliteAnchor` live in `gps_denied.hot_types.satellite_anchor`.
+"""
 
-from gps_denied.schemas import GPSPoint
+from gps_denied.hot_types.satellite_anchor import (  # noqa: F401
+    SatelliteAnchor,
+    TileBounds,
+    TileCoords,
+)
 
-
-class TileCoords(BaseModel):
-    """Web Mercator tile coordinates."""
-    x: int
-    y: int
-    zoom: int
-
-
-class TileBounds(BaseModel):
-    """GPS boundaries of a tile."""
-    nw: GPSPoint
-    ne: GPSPoint
-    sw: GPSPoint
-    se: GPSPoint
-    center: GPSPoint
-    gsd: float  # Ground Sampling Distance (meters/pixel)
+__all__ = [
+    "SatelliteAnchor",
+    "TileBounds",
+    "TileCoords",
+]

src/gps_denied/schemas/vo.py

@@ -1,49 +1,21 @@
-"""Sequential Visual Odometry schemas (Component F07)."""
+"""Sequential Visual Odometry schemas (Component F07).
 
-from typing import Optional
+Phase 1 shim — `Features`, `Matches`, `RelativePose`, `Motion` and the
+ARCH-02 alias `VOEstimate` live in `gps_denied.hot_types.vo_estimate`.
+"""
 
-import numpy as np
-from pydantic import BaseModel
+from gps_denied.hot_types.vo_estimate import (  # noqa: F401
+    Features,
+    Matches,
+    Motion,
+    RelativePose,
+    VOEstimate,
+)
 
-
-class Features(BaseModel):
-    """Extracted image features (e.g., from SuperPoint)."""
-    model_config = {"arbitrary_types_allowed": True}
-
-    keypoints: np.ndarray  # (N, 2)
-    descriptors: np.ndarray  # (N, 256)
-    scores: np.ndarray  # (N,)
-
-
-class Matches(BaseModel):
-    """Matches between two sets of features (e.g., from LightGlue)."""
-    model_config = {"arbitrary_types_allowed": True}
-
-    matches: np.ndarray  # (M, 2)
-    scores: np.ndarray  # (M,)
-    keypoints1: np.ndarray  # (M, 2)
-    keypoints2: np.ndarray  # (M, 2)
-
-
-class RelativePose(BaseModel):
-    """Relative pose between two frames."""
-    model_config = {"arbitrary_types_allowed": True}
-
-    translation: np.ndarray  # (3,)
-    rotation: np.ndarray  # (3, 3)
-    confidence: float
-    inlier_count: int
-    total_matches: int
-    tracking_good: bool
-    scale_ambiguous: bool = True
-    chunk_id: Optional[str] = None
-
-
-class Motion(BaseModel):
-    """Motion estimate from OpenCV."""
-    model_config = {"arbitrary_types_allowed": True}
-
-    translation: np.ndarray  # (3,) unit vector
-    rotation: np.ndarray  # (3, 3) rotation matrix
-    inliers: np.ndarray  # Boolean mask of inliers
-    inlier_count: int
+__all__ = [
+    "Features",
+    "Matches",
+    "Motion",
+    "RelativePose",
+    "VOEstimate",
+]

src/gps_denied/testing/benchmark.py

@@ -0,0 +1,371 @@
+"""Accuracy Benchmark (Phase 7).
+
+Provides:
+  - SyntheticTrajectory  — generates a realistic fixed-wing UAV flight path
+                           with ground-truth GPS + noisy sensor data.
+  - AccuracyBenchmark    — replays a trajectory through the ESKF pipeline
+                           and computes position-error statistics.
+
+Acceptance criteria (from solution.md):
+  AC-PERF-1: 80 % of frames within 50 m of ground truth.
+  AC-PERF-2: 60 % of frames within 20 m of ground truth.
+  AC-PERF-3: End-to-end per-frame latency < 400 ms.
+  AC-PERF-4: VO drift over 1 km straight segment (no sat correction) < 100 m.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+import numpy as np
+
+from gps_denied.core.coordinates import CoordinateTransformer
+from gps_denied.core.eskf import ESKF
+from gps_denied.schemas import GPSPoint
+from gps_denied.schemas.eskf import ESKFConfig, IMUMeasurement
+
+# ---------------------------------------------------------------------------
+# Synthetic trajectory
+# ---------------------------------------------------------------------------
+
+@dataclass
+class TrajectoryFrame:
+    """One simulated camera frame with ground-truth and noisy sensor data."""
+    frame_id: int
+    timestamp: float
+    true_position_enu: np.ndarray     # (3,) East, North, Up in metres
+    true_gps: GPSPoint                # WGS84 from true ENU
+    imu_measurements: list[IMUMeasurement]  # High-rate IMU between frames
+    vo_translation: Optional[np.ndarray]    # Noisy relative displacement (3,)
+    vo_tracking_good: bool = True
+
+
+@dataclass
+class SyntheticTrajectoryConfig:
+    """Parameters for trajectory generation."""
+    # Origin (mission start)
+    origin: GPSPoint = field(default_factory=lambda: GPSPoint(lat=49.0, lon=32.0))
+    altitude_m: float = 600.0           # Constant AGL altitude (m)
+    # UAV speed and heading
+    speed_mps: float = 20.0             # ~70 km/h (typical fixed-wing)
+    heading_deg: float = 45.0           # Initial heading (degrees CW from North)
+    camera_fps: float = 0.7             # ADTI 20L V1 camera rate (Hz)
+    imu_hz: float = 200.0               # IMU sample rate
+    num_frames: int = 50                # Number of camera frames to simulate
+    # Noise parameters
+    vo_noise_m: float = 0.5             # VO translation noise (sigma, metres)
+    imu_accel_noise: float = 0.01       # Accelerometer noise sigma (m/s²)
+    imu_gyro_noise: float = 0.001       # Gyroscope noise sigma (rad/s)
+    # Failure injection
+    vo_failure_frames: list[int] = field(default_factory=list)
+    # Waypoints for heading changes (ENU East, North metres from origin)
+    waypoints_enu: list[tuple[float, float]] = field(default_factory=list)
+
+
+class SyntheticTrajectory:
+    """Generate a synthetic fixed-wing UAV flight with ground truth + noisy sensors."""
+
+    def __init__(self, config: SyntheticTrajectoryConfig | None = None):
+        self.config = config or SyntheticTrajectoryConfig()
+        self._coord = CoordinateTransformer()
+        self._flight_id = "__synthetic__"
+        self._coord.set_enu_origin(self._flight_id, self.config.origin)
+
+    def generate(self) -> list[TrajectoryFrame]:
+        """Generate all trajectory frames."""
+        cfg = self.config
+        dt_camera = 1.0 / cfg.camera_fps
+        dt_imu = 1.0 / cfg.imu_hz
+        imu_steps = int(dt_camera * cfg.imu_hz)
+
+        frames: list[TrajectoryFrame] = []
+        pos = np.array([0.0, 0.0, cfg.altitude_m])
+        vel = self._heading_to_enu_vel(cfg.heading_deg, cfg.speed_mps)
+        prev_pos = pos.copy()
+        t = time.time()
+
+        waypoints = list(cfg.waypoints_enu)  # copy
+
+        for fid in range(cfg.num_frames):
+            # --- Waypoint steering ---
+            if waypoints:
+                wp_e, wp_n = waypoints[0]
+                to_wp = np.array([wp_e - pos[0], wp_n - pos[1], 0.0])
+                dist_wp = np.linalg.norm(to_wp[:2])
+                if dist_wp < cfg.speed_mps * dt_camera:
+                    waypoints.pop(0)
+                else:
+                    heading_rad = math.atan2(to_wp[0], to_wp[1])  # ENU: E=X, N=Y
+                    vel = np.array([
+                        cfg.speed_mps * math.sin(heading_rad),
+                        cfg.speed_mps * math.cos(heading_rad),
+                        0.0,
+                    ])
+
+            # --- Simulate IMU between frames ---
+            imu_list: list[IMUMeasurement] = []
+            for step in range(imu_steps):
+                ts = t + step * dt_imu
+                # Body-frame acceleration (mostly gravity correction, small forward accel)
+                accel_true = np.array([0.0, 0.0, 9.81])  # gravity compensation
+                gyro_true = np.zeros(3)
+                imu = IMUMeasurement(
+                    accel=accel_true + np.random.randn(3) * cfg.imu_accel_noise,
+                    gyro=gyro_true + np.random.randn(3) * cfg.imu_gyro_noise,
+                    timestamp=ts,
+                )
+                imu_list.append(imu)
+
+            # --- Propagate position ---
+            prev_pos = pos.copy()
+            pos = pos + vel * dt_camera
+            t += dt_camera
+
+            # --- True GPS from ENU position ---
+            true_gps = self._coord.enu_to_gps(
+                self._flight_id, (float(pos[0]), float(pos[1]), float(pos[2]))
+            )
+
+            # --- VO measurement (relative displacement + noise) ---
+            true_displacement = pos - prev_pos
+            vo_tracking_good = fid not in cfg.vo_failure_frames
+            if vo_tracking_good:
+                noisy_displacement = true_displacement + np.random.randn(3) * cfg.vo_noise_m
+                noisy_displacement[2] = 0.0  # monocular VO is scale-ambiguous in Z
+            else:
+                noisy_displacement = None
+
+            frames.append(TrajectoryFrame(
+                frame_id=fid,
+                timestamp=t,
+                true_position_enu=pos.copy(),
+                true_gps=true_gps,
+                imu_measurements=imu_list,
+                vo_translation=noisy_displacement,
+                vo_tracking_good=vo_tracking_good,
+            ))
+
+        return frames
+
+    @staticmethod
+    def _heading_to_enu_vel(heading_deg: float, speed_mps: float) -> np.ndarray:
+        """Convert heading (degrees CW from North) to ENU velocity vector."""
+        rad = math.radians(heading_deg)
+        return np.array([
+            speed_mps * math.sin(rad),   # East
+            speed_mps * math.cos(rad),   # North
+            0.0,                         # Up
+        ])
+
+
+# ---------------------------------------------------------------------------
+# Accuracy Benchmark
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BenchmarkResult:
+    """Position error statistics over a trajectory replay."""
+    errors_m: list[float]               # Per-frame horizontal error in metres
+    latencies_ms: list[float]           # Per-frame process time in ms
+    frames_total: int
+    frames_with_good_estimate: int
+
+    @property
+    def p80_error_m(self) -> float:
+        """80th percentile position error (metres)."""
+        return float(np.percentile(self.errors_m, 80)) if self.errors_m else float("inf")
+
+    @property
+    def p60_error_m(self) -> float:
+        """60th percentile position error (metres)."""
+        return float(np.percentile(self.errors_m, 60)) if self.errors_m else float("inf")
+
+    @property
+    def median_error_m(self) -> float:
+        """Median position error (metres)."""
+        return float(np.median(self.errors_m)) if self.errors_m else float("inf")
+
+    @property
+    def max_error_m(self) -> float:
+        return float(max(self.errors_m)) if self.errors_m else float("inf")
+
+    @property
+    def p95_latency_ms(self) -> float:
+        """95th percentile frame latency (ms)."""
+        return float(np.percentile(self.latencies_ms, 95)) if self.latencies_ms else float("inf")
+
+    @property
+    def pct_within_50m(self) -> float:
+        """Fraction of frames within 50 m error."""
+        if not self.errors_m:
+            return 0.0
+        return sum(e <= 50.0 for e in self.errors_m) / len(self.errors_m)
+
+    @property
+    def pct_within_20m(self) -> float:
+        """Fraction of frames within 20 m error."""
+        if not self.errors_m:
+            return 0.0
+        return sum(e <= 20.0 for e in self.errors_m) / len(self.errors_m)
+
+    def passes_acceptance_criteria(self) -> tuple[bool, dict[str, bool]]:
+        """Check all solution.md acceptance criteria.
+
+        Returns (overall_pass, per_criterion_dict).
+        """
+        checks = {
+            "AC-PERF-1: 80% within 50m": self.pct_within_50m >= 0.80,
+            "AC-PERF-2: 60% within 20m": self.pct_within_20m >= 0.60,
+            "AC-PERF-3: p95 latency < 400ms": self.p95_latency_ms < 400.0,
+        }
+        overall = all(checks.values())
+        return overall, checks
+
+    def summary(self) -> str:
+        overall, checks = self.passes_acceptance_criteria()
+        lines = [
+            f"Frames: {self.frames_total}  |  with estimate: {self.frames_with_good_estimate}",
+            f"Error  — median: {self.median_error_m:.1f}m  p80: {self.p80_error_m:.1f}m  "
+            f"p60: {self.p60_error_m:.1f}m  max: {self.max_error_m:.1f}m",
+            f"Within 50m: {self.pct_within_50m*100:.1f}%  |  within 20m: {self.pct_within_20m*100:.1f}%",
+            f"Latency p95: {self.p95_latency_ms:.1f}ms",
+            "",
+            "Acceptance criteria:",
+        ]
+        for criterion, passed in checks.items():
+            lines.append(f"  {'PASS' if passed else 'FAIL'}  {criterion}")
+        lines.append(f"\nOverall: {'PASS' if overall else 'FAIL'}")
+        return "\n".join(lines)
+
+
+class AccuracyBenchmark:
+    """Replays a SyntheticTrajectory through the ESKF and measures accuracy.
+
+    The benchmark uses only the ESKF (no full FlightProcessor) for speed.
+    Satellite corrections are injected optionally via sat_correction_fn.
+    """
+
+    def __init__(
+        self,
+        eskf_config: ESKFConfig | None = None,
+        sat_correction_fn: Optional[Callable[[TrajectoryFrame], Optional[np.ndarray]]] = None,
+    ):
+        """
+        Args:
+            eskf_config:        ESKF tuning parameters.
+            sat_correction_fn:  Optional callback(frame) → ENU position or None.
+                                Called on keyframes to inject satellite corrections.
+                                If None, no satellite corrections are applied.
+        """
+        self.eskf_config = eskf_config or ESKFConfig()
+        self.sat_correction_fn = sat_correction_fn
+
+    def run(
+        self,
+        trajectory: list[TrajectoryFrame],
+        origin: GPSPoint,
+        satellite_keyframe_interval: int = 7,
+    ) -> BenchmarkResult:
+        """Replay trajectory frames through ESKF, collect errors and latencies.
+
+        Args:
+            trajectory:                  List of TrajectoryFrame (from SyntheticTrajectory).
+            origin:                      WGS84 reference origin for ENU.
+            satellite_keyframe_interval: Apply satellite correction every N frames.
+        """
+        coord = CoordinateTransformer()
+        flight_id = "__benchmark__"
+        coord.set_enu_origin(flight_id, origin)
+
+        eskf = ESKF(self.eskf_config)
+        # Init at origin with HIGH uncertainty
+        eskf.initialize(np.array([0.0, 0.0, trajectory[0].true_position_enu[2]]),
+                        trajectory[0].timestamp)
+
+        errors_m: list[float] = []
+        latencies_ms: list[float] = []
+        frames_with_estimate = 0
+
+        for frame in trajectory:
+            t_frame_start = time.perf_counter()
+
+            # --- IMU prediction ---
+            for imu in frame.imu_measurements:
+                eskf.predict(imu)
+
+            # --- VO update ---
+            if frame.vo_tracking_good and frame.vo_translation is not None:
+                dt_vo = 1.0 / 0.7  # camera interval
+                eskf.update_vo(frame.vo_translation, dt_vo)
+
+            # --- Satellite update (keyframes) ---
+            if frame.frame_id % satellite_keyframe_interval == 0:
+                sat_pos_enu: Optional[np.ndarray] = None
+                if self.sat_correction_fn is not None:
+                    sat_pos_enu = self.sat_correction_fn(frame)
+                else:
+                    # Default: inject ground-truth position + realistic noise
+                    noise_m = 10.0
+                    sat_pos_enu = (
+                        frame.true_position_enu[:3]
+                        + np.random.randn(3) * noise_m
+                    )
+                    sat_pos_enu[2] = frame.true_position_enu[2]  # keep altitude
+
+                if sat_pos_enu is not None:
+                    # Tell ESKF the measurement noise matches what we inject
+                    eskf.update_satellite(sat_pos_enu, noise_meters=noise_m)
+
+            latency_ms = (time.perf_counter() - t_frame_start) * 1000.0
+            latencies_ms.append(latency_ms)
+
+            # --- Compute horizontal error vs ground truth ---
+            if eskf.initialized and eskf._nominal_state is not None:
+                est_pos = eskf._nominal_state["position"]
+                true_pos = frame.true_position_enu
+                horiz_error = float(np.linalg.norm(est_pos[:2] - true_pos[:2]))
+                errors_m.append(horiz_error)
+                frames_with_estimate += 1
+            else:
+                errors_m.append(float("inf"))
+
+        return BenchmarkResult(
+            errors_m=errors_m,
+            latencies_ms=latencies_ms,
+            frames_total=len(trajectory),
+            frames_with_good_estimate=frames_with_estimate,
+        )
+
+    def run_vo_drift_test(
+        self,
+        trajectory_length_m: float = 1000.0,
+        speed_mps: float = 20.0,
+    ) -> float:
+        """Measure VO drift over a straight segment with NO satellite correction.
+
+        Returns final horizontal position error in metres.
+        Per solution.md, this should be < 100m over 1km.
+        """
+        fps = 0.7
+        num_frames = max(10, int(trajectory_length_m / speed_mps * fps))
+        cfg = SyntheticTrajectoryConfig(
+            speed_mps=speed_mps,
+            heading_deg=0.0,   # straight North
+            camera_fps=fps,
+            num_frames=num_frames,
+            vo_noise_m=0.3,    # cuVSLAM-grade VO noise
+        )
+        traj_gen = SyntheticTrajectory(cfg)
+        frames = traj_gen.generate()
+
+        # No satellite corrections
+        benchmark_no_sat = AccuracyBenchmark(
+            eskf_config=self.eskf_config,
+            sat_correction_fn=lambda _: None,  # suppress all satellite updates
+        )
+        result = benchmark_no_sat.run(frames, cfg.origin, satellite_keyframe_interval=9999)
+        # Return final-frame error
+        return result.errors_m[-1] if result.errors_m else float("inf")