Epic E4: break src.ino into translation units #212

_{Recreated from Strycher/Field_Compass-archive#212 — originally opened by @Strycher on 2026-09-05. Credentials redacted where present.}

Parent feature: #151 · Plan: docs/plans/2026-08-09-platformio-hal-design.md

E4 of #151's sequence: E1 vendor config → E2 PlatformIO → E3 CI gate → E4 translation units → E5 HAL

Break src/src.ino into translation units. It is 8,712 lines in one file, which blocks parallel agent work, forces the per-issue branching override in CLAUDE.md, and prevents the Epic branch model CLAUDE-BASE mandates.

Sequencing: E3 (CI) has left #151 to become its own Feature. Owner ruling: CI lands first. E4 does not start until the CI Feature's compile-gate half is in place.

Diagnosis (task #215)

Measured, with provenance. [TOOL] = real tool output; [REGEX] = pattern-matching over the source, not yet cross-validated.

Hot core: gpsData (19), sdAvailable (18), framAvailable (16), useMetricUnits (16), settingsSubScreen (15), currentScreen (15), useFahrenheit (15), cacheListCount (15).

Hard blocker found by diagnosis

Five state blobs are anonymous structs with a single instance — struct { bool valid; float latitude; ... } gpsData; — namely gpsData (113 refs), envData (58), imuData (35), shtData (29), weatherTrend (24).

extern cannot name a variable of anonymous struct type. Putting the anonymous struct in a header gives each TU a distinct type plus duplicate definitions; extern decltype(gpsData) gpsData; is circular. Naming them is a prerequisite, and it touches declarations only — all usage sites are unchanged.

Structure — ownership first, no globals.h

Owner ruling: no transitional externs header at any point. Each unit takes owned state with it, so ownership precedes extraction.

Stage 1 — prerequisites, no extraction

• 1.1 name the 5 anonymous structs
• 1.2 file-scope #defines → include/fc_config.h
• 1.3 type declarations → include/fc_types.h
• 1.4 cross-validate the [REGEX] inventory against nm, and build the per-extraction harness

Stage 2 — hot-core ownership. Peripherals {sdAvailable, framAvailable}, UiState {currentScreen, settingsSubScreen}, UnitPrefs {useMetricUnits, useFahrenheit}, geocache unit {cacheListCount}. Behaviour-neutral, still inside src.ino.

Stage 3 — vertical slices, cheapest first. Each takes its state with it.

logging ordering is not negotiable: logPrintf has 52 callers, logPrintln 40, sdOpenSafe 14 — bottom of the dependency stack.

Stage 4 — heavy consumers and screens. weather 638 / web 1,063 (47 externs but only 1 export, a leaf consumer) / screen_settings 1,490 / screen_geocache 1,337 / lvgl_core 794 / screen_telemetry 330 / screen_environment 201 / screen_compass 76.

Residue: ~567 lines (setup, loop, buttons, display sleep) stay in src/src.ino.

Per-extraction verification

Proven on #186: identical size totals do not prove behaviour-neutrality — symbol set, sizes and types were identical across 14,958 symbols while 608 addresses shifted, because link order follows TU name.

pio run -e feather_s3
xtensa-esp32s3-elf-nm --print-size --defined-only .pio/build/feather_s3/firmware.elf | sort

Each extraction asserts: build exits 0; RAM/Flash totals unchanged or the delta explained; symbol set, sizes and types identical; address shifts reported not hidden; arduino-cli compile ... src/ still builds while #161 is open; hardware verification before merge.

Exit criteria

• No translation unit exceeds ~1,500 lines
• No globals.h of externs exists at any point
• Parallel agent work is possible — two agents can edit different units without conflict
• The per-issue branching override in CLAUDE.md is re-evaluated, since its only justification was this file

Stages become Tasks once the owner grants them. Full plan: cheerful-enchanting-pearl.md.