Revise acceptance criteria and restrictions documentation to clarify recent updates and specifications. Key changes include enhanced definitions for position accuracy, image processing quality, and operational parameters, as well as updates to camera specifications and validation requirements. This revision aims to improve clarity and ensure alignment with project goals.

2026-06-21 08:21:13 +00:00 · 2026-05-01 16:24:46 +03:00
parent 3f173c1bb7
commit 7e15868d39
62 changed files with 6878 additions and 13 deletions
@@ -0,0 +1,11 @@
+# Deployment Planning Index
+
+This directory contains the system-level deployment plan produced during Plan Step 2:
+
+- `containerization.md`
+- `ci_cd_pipeline.md`
+- `environment_strategy.md`
+- `observability.md`
+- `deployment_procedures.md`
+
+Component-specific implementation tasks are created later during decomposition.
@@ -0,0 +1,54 @@
+# CI/CD Pipeline
+
+## Pipeline Stages
+
+| Stage | Runs On | Gate |
+|-------|---------|------|
+| Format/lint | PR | Block merge |
+| Unit tests | PR | Block merge |
+| Replay black-box smoke | PR | Block merge |
+| Cache/security fixture tests | PR | Block merge |
+| Plane SITL spoof/failsafe tests | Release candidate / nightly | Block release |
+| Public dataset replay | Nightly / release candidate | Block release |
+| Jetson latency/resource tests | Release candidate | Block release |
+| Thermal/FDR endurance | Release candidate / hardware qualification | Block release |
+
+## Artifact Outputs
+
+- Test CSV reports.
+- FDR validation summaries.
+- Cache integrity reports.
+- Dataset replay metrics.
+- SITL tlogs.
+- Jetson profiling traces.
+
+## Caching
+
+- Cache dependency builds by lockfile hash.
+- Cache public dataset slices only in controlled CI storage with license metadata.
+- Do not cache secrets or signing keys.
+
+## Branch Policy
+
+- Work occurs on `dev`.
+- Release gates must pass before deploy artifacts are considered production-ready.
+- Any failed safety, spoofing, false-position, or cache-poisoning test blocks release.
+
+## Quality Gates
+
+| Gate | Threshold |
+|------|-----------|
+| Still-image geolocation | >=80% within 50 m and >=50% within 20 m |
+| Hot-path latency | <400 ms p95 |
+| Memory | <8 GB shared |
+| Cold start | <30 s p95 |
+| FDR | <=64 GB / 8-hour flight |
+| Cache storage | <=10 GB unless split budget is approved |
+| False position | AC-NEW-4 thresholds |
+
+## Open Tasks For Decomposition
+
+- Define CI runner labels for Docker/replay vs Jetson local hardware.
+- Add dataset-license checks before public dataset jobs.
+- Implement SITL scenario generation and tlog validation job.
+- Implement report collation into a release evidence bundle.
@@ -0,0 +1,46 @@
+# Containerization
+
+## Strategy
+
+The production runtime targets Jetson hardware and may not be fully containerized for all camera/GPU paths. The test and development stack uses containers where practical, with local hardware execution required for release gates.
+
+## Runtime Units
+
+| Unit | Containerized? | Notes |
+|------|----------------|-------|
+| GPS-denied service | Optional on Jetson | Must access camera, CUDA/TensorRT/ONNX, MAVLink, local cache, FDR storage |
+| Replay consumer | Yes | Deterministic black-box test harness |
+| Satellite cache stub | Yes | Local fixture volume for COG/manifest/descriptors |
+| ArduPilot Plane SITL | Yes or local process | Used for MAVLink and failsafe validation |
+| QGC observer/log parser | Yes | Parses MAVLink status/tlogs |
+
+## Docker Compose Profiles
+
+| Profile | Purpose | Services |
+|---------|---------|----------|
+| `replay` | CI/PR deterministic fixture tests | gps-denied-service, replay-consumer, satellite-cache-stub |
+| `sitl` | ArduPilot Plane integration tests | gps-denied-service, ardupilot-plane-sitl, qgc-observer |
+| `jetson-local` | Documentation-only profile for local hardware run | Host runtime with local scripts/tasks created later |
+
+## Image Requirements
+
+- Base images must match JetPack/CUDA compatibility for GPU tests.
+- Replay-only images may use standard Ubuntu/Python/C++ build images.
+- No production image should contain secrets, mission signing keys, or provider credentials.
+- Dataset downloads are not baked into images; they are mounted as versioned fixtures.
+
+## Volumes
+
+| Volume | Purpose |
+|--------|---------|
+| `/data/input` | Test images and public dataset slices |
+| `/cache/satellite` | Offline cache fixture |
+| `/fdr` | Runtime FDR output |
+| `/test-results` | CSV/Markdown reports |
+
+## Open Tasks For Decomposition
+
+- Create Dockerfiles for replay-compatible service and consumer harness.
+- Define Jetson local setup scripts for GPU/camera/MAVLink access.
+- Create compose profiles for replay and SITL.
+- Add license-aware public dataset fixture downloader.
@@ -0,0 +1,68 @@
+# Deployment Procedures
+
+## Deployment Targets
+
+| Target | Purpose |
+|--------|---------|
+| Replay environment | Development and CI fixtures |
+| Plane SITL | MAVLink/failsafe validation |
+| Jetson companion computer | Production runtime and release gating |
+| Representative flight/replay rig | Final acceptance evidence |
+
+## Pre-Deployment Checklist
+
+- Camera lens, resolution, FPS, sensor dimensions, and operating temperature are manufacturer-verified.
+- Camera intrinsics/extrinsics are calibrated and versioned.
+- BASALT, OpenCV, FAISS, LightGlue, DINOv2/ONNX/TensorRT dependencies are pinned.
+- TensorRT/ONNX descriptor-fidelity tests pass before optimized engines are used.
+- Satellite cache manifests and sidecars validate signatures, hashes, freshness, and resolution.
+- Plane SITL validates `GPS_INPUT` behavior with production parameters.
+- Jetson latency, memory, and thermal release gates pass.
+- FDR rollover test passes.
+
+## Deployment Steps
+
+1. Install JetPack-compatible runtime dependencies on the companion computer.
+2. Install/build BASALT and native vision dependencies.
+3. Pre-build any ONNX/TensorRT engines accepted by fidelity tests.
+4. Sync mission cache from Satellite Service before flight.
+5. Validate cache manifest, descriptors, signatures, resolution, and freshness.
+6. Start the onboard service and verify FC telemetry connection.
+7. Run cold-start first-fix check.
+8. Confirm QGroundControl status and FDR segment creation.
+
+## Health Checks
+
+| Check | Pass Condition |
+|-------|----------------|
+| Camera input | Frames received with expected resolution/rate |
+| FC telemetry | IMU/attitude/altitude/GPS-health stream healthy |
+| Cache | Manifest and descriptor index valid |
+| First fix | Valid `GPS_INPUT` <30 s p95 in cold-start test |
+| Resource health | Memory <8 GB, no thermal throttle |
+| QGC status | Status visible at configured downsample rate |
+| FDR | Segment open and writable |
+
+## Rollback
+
+- If runtime dependency update fails tests, revert to previous pinned build.
+- If cache manifest validation fails, reject the mission cache and resync/rebuild before flight.
+- If optimized engine fidelity fails, fall back to PyTorch/ONNX path that passed descriptor tests.
+- If BASALT candidate fails representative replay gates, evaluate Kimera backup or custom fallback tasks before production deployment.
+
+## Post-Flight Procedure
+
+1. Stop the onboard service cleanly.
+2. Export FDR summary and integrity hashes.
+3. Package generated tiles with sidecars and manifest delta.
+4. Upload generated tile package to Satellite Service when connectivity is available.
+5. Archive release evidence: tlogs, FDR summary, cache validation report, test results.
+
+## Deployment Blockers
+
+- ADTi camera spec mismatch unresolved for FPS/resolution/lens/temperature.
+- Missing representative synchronized nav-camera + FC telemetry + ground truth for final acceptance.
+- Any false-position safety budget failure.
+- Any cache-poisoning gate failure.
+- Any Plane SITL `GPS_INPUT` failure.
+- Thermal throttling during the 8-hour target workload.
@@ -0,0 +1,49 @@
+# Environment Strategy
+
+## Environments
+
+| Environment | Purpose | Hardware |
+|-------------|---------|----------|
+| Development replay | Fast local iteration with fixtures | Developer workstation |
+| CI replay | Deterministic PR checks | Docker runner |
+| Public dataset replay | Nightly/RC algorithm validation | Docker or GPU runner |
+| Plane SITL | MAVLink/failsafe validation | Docker/local SITL |
+| Jetson hardware validation | Production path latency, memory, GPU, camera, thermal | Jetson Orin Nano Super |
+| Representative flight/replay | Final acceptance evidence | Target-like UAV/FC/camera setup |
+
+## Configuration Classes
+
+| Config | Development | Production |
+|--------|-------------|------------|
+| Satellite cache | Small fixture | Full mission cache |
+| PostgreSQL/PostGIS | Local test DB with fixture manifests | Local onboard DB with signed mission manifests, spatial metadata, and FDR event indexes |
+| Descriptor index | Small FAISS index | Full operational-area index |
+| MAVLink | SITL/replay | Physical FC link |
+| FDR | Temporary directory | Per-flight NVMe directory with rollover |
+| Dataset fixtures | Optional public slices | Not used at runtime |
+
+## Secrets And Signing
+
+- Mission signing keys are never committed.
+- Test keys may be committed only if clearly labeled as non-production.
+- Provider credentials are not used by onboard runtime.
+- Any Satellite Service sync credentials are post-flight/deployment environment secrets.
+
+## Dataset Licensing
+
+Public datasets must be tagged before use:
+
+| Dataset | Expected Use | License Constraint |
+|---------|--------------|--------------------|
+| MUN-FRL | Preferred public VIO/nadir replay | CC BY 4.0 per current docs |
+| ALTO | Preferred aerial localization/VPR replay | BSD-3 repository; dataset availability must be pinned |
+| Kagaru | Fixed-wing/farmland validation candidate | Verify terms before commercial use |
+| EPFL fixed-wing | Fixed-wing validation candidate | Verify terms before commercial use |
+| VPAir | VPR/localization only | Academic-use restriction likely blocks commercial acceptance |
+| UZH FPV | VIO stress proxy only | Non-commercial license blocks commercial acceptance |
+
+## Promotion Rules
+
+- A result from public datasets can de-risk implementation but cannot replace representative acceptance data.
+- A release candidate cannot be promoted without Jetson hardware validation and Plane SITL.
+- A mission cache cannot be used if manifest/signature/freshness validation fails.
@@ -0,0 +1,61 @@
+# Observability
+
+## Goals
+
+- Explain every emitted position estimate.
+- Detect false-position risk before it reaches the flight controller.
+- Preserve enough evidence to replay incidents without storing raw frames.
+- Surface operator-relevant status to QGroundControl without saturating telemetry.
+
+## Runtime Signals
+
+| Signal | Frequency | Destination | Notes |
+|--------|-----------|-------------|-------|
+| Position estimate | Per processed frame locally | FDR, MAVLink `GPS_INPUT` | GCS receives downsampled status |
+| Source label | Per estimate | FDR, status summary | `satellite_anchored`, `vo_extrapolated`, `dead_reckoned` |
+| Covariance semi-major | Per estimate | FDR, `GPS_INPUT.horiz_accuracy` mapping | Must not under-report |
+| Anchor decision | Per candidate | FDR | Include MRE, inliers, tile provenance, rejection reason |
+| Cache validation | On cache load / tile read | FDR, health log | Signature, freshness, resolution, hash |
+| Blackout/spoofing status | On transition and 1-2 Hz while active | QGC, FDR | Operator status |
+| Total occlusion status | Per transition and sampled while active | FDR, QGC if persistent | Indicates VIO is bypassed and IMU-only propagation is active |
+| Resource health | 1 Hz or configurable | FDR, QGC warning on threshold | CPU/GPU/temp/memory/throttle |
+| Tile write decision | Per generated tile | FDR, sidecar | Include parent covariance and trust level |
+
+## Logs
+
+| Log Type | Format | Retention |
+|----------|--------|-----------|
+| FDR events/index | PostgreSQL tables + CBOR payload segments | <=64 GB per flight, rollover |
+| MAVLink raw stream | tlog or equivalent | FDR cap |
+| Health metrics | FDR event stream | FDR cap |
+| Test reports | CSV/Markdown | CI artifact retention |
+
+## Alerts And Status Text
+
+| Condition | Status |
+|-----------|--------|
+| Visual blackout starts | `VISUAL_BLACKOUT_IMU_ONLY` |
+| Total occlusion before VIO | `VISUAL_OCCLUSION_IMU_ONLY` |
+| Blackout failsafe threshold exceeded | `VISUAL_BLACKOUT_FAILSAFE` |
+| Spoofing promotion/demotion | QGC status text with mode and timestamp |
+| Stale cache tile rejected | Warning in FDR; QGC only if mission-impacting |
+| Thermal throttle risk | QGC warning before throttle if possible |
+| No estimate for threshold | Relocalization request / failsafe status |
+
+## Metrics For Release Evidence
+
+- Error CDF against ground truth.
+- Anchor-age binned error.
+- Covariance calibration plot.
+- VIO completion rate.
+- Relocalization trigger-to-anchor latency.
+- Cache freshness rejection counts.
+- FDR size over 8 hours.
+- Thermal/throttle timeline.
+
+## Open Tasks For Decomposition
+
+- Define FDR schema and event names.
+- Define QGC status vocabulary and rate limiting.
+- Define telemetry-to-report export tooling.
+- Define covariance calibration dashboard/report.