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

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.