# FDR And Observability

## 1. High-Level Overview

**Purpose**: Record bounded, replayable mission evidence and expose runtime health/status events for analysis and operator awareness.

**Architectural Pattern**: Append-only event sink + exporter.

**Upstream dependencies**: All runtime components.

**Downstream consumers**: Validation harness, post-flight audit tools, QGC status through MAVLink component.

## 2. Internal Interfaces

### Interface: `FlightRecorder`

| Method | Input | Output | Async | Error Types |
|--------|-------|--------|-------|-------------|
| `append_event` | `FdrEvent` | `AppendResult` | Yes | `RecorderUnavailable`, `StorageFull` |
| `rollover` | `RolloverRequest` | `FdrSegmentInfo` | No | `RolloverFailed` |
| `export` | `ExportRequest` | `ExportResult` | Yes | `ExportFailed` |

## 3. Data Access Patterns

| Query | Frequency | Hot Path | Index Needed |
|-------|-----------|----------|--------------|
| Append event | High | Yes | Append index only |
| Export by time/type | Post-flight | No | Time/type index |

### Storage Estimates

| Table/Collection | Est. Row Count | Row Size | Total Size | Growth Rate |
|------------------|----------------|----------|------------|-------------|
| FDR events | Flight-dependent | Mixed | <=64 GB per 8 h | Per flight |

## 4. Implementation Details

**State Management**: Owns active segment, rollover policy, and export state.

**Key Dependencies**:

| Library | Purpose |
|---------|---------|
| PostgreSQL client | Event metadata, time/type indexes, mission query surface |
| CBOR writer | Bounded runtime payload segments |
| Parquet writer | Optional post-flight export |

**Error Handling Strategy**:
- Storage-full emits critical status and starts rollover/retention behavior.
- Append failures are surfaced to the caller and health system.

## 5. Caveats & Edge Cases

**Known limitations**:
- Raw frames are not retained by default; only metadata, decisions, hashes, and occlusion/blackout status are recorded.
- PostgreSQL availability is required for indexed FDR metadata; CBOR payload segments preserve bounded append behavior for high-volume data.

**Performance bottlenecks**:
- FDR appends must not block hot-path localization.

## 6. Dependency Graph

**Must be implemented after**: event schema and key DTOs.

**Can be implemented in parallel with**: MAVLink integration.

**Blocks**: release evidence and most validation reports.

## 7. Logging Strategy

| Log Level | When | Example |
|-----------|------|---------|
| ERROR | Recorder unavailable | `fdr_unavailable path=...` |
| WARN | Rollover occurs | `fdr_rollover segment=...` |
| INFO | Export complete | `fdr_export_complete format=parquet` |

**Log format**: FDR event metadata plus local health logs.

**Log storage**: PostgreSQL FDR event tables plus CBOR segment payloads.