chore: unify HA manufacturer and add refactor guards

docs/REFRACTOR_NOTES.md

@@ -0,0 +1,77 @@
+# Refactor Notes: `main.cpp` Split
+
+## Architecture
+
+The firmware remains a unified image. Role selection is still done at boot in `src/main.cpp` using the role pin. `src/main.cpp` is now a thin coordinator that:
+
+- detects role and initializes shared platform subsystems,
+- creates role module config,
+- calls `begin()` once,
+- delegates runtime via `loop()`.
+
+## Sender Logic
+
+Sender-only runtime now lives in:
+
+- `src/sender_state_machine.h`
+- `src/sender_state_machine.cpp`
+
+Public API:
+
+- `SenderStateMachineConfig`
+- `SenderStats`
+- `SenderStateMachine::begin(...)`
+- `SenderStateMachine::loop()`
+- `SenderStateMachine::stats()`
+
+Sender state machine exposes explicit states (`Syncing`, `Normal`, `Catchup`, `WaitAck`) and keeps sender flow isolated from top-level orchestration.
+
+Sender helpers:
+
+- `handleMeterRead(...)`
+- `maybeSendBatch(...)`
+- `handleAckWindow(...)`
+- `applyTimeFromAck(...)`
+- `validateInvariants()`
+
+Sender invariants are checked and debug-traceable (`DD3_DEBUG`) for:
+
+- single inflight batch at a time,
+- ACK acceptance only for matching `batch_id`,
+- retry bounded by `BATCH_MAX_RETRIES`,
+- queue depth bounded by `BATCH_QUEUE_DEPTH`.
+
+## Receiver Logic
+
+Receiver-only runtime now lives in:
+
+- `src/receiver_pipeline.h`
+- `src/receiver_pipeline.cpp`
+
+Shared receiver arrays and fault/discovery state used by setup wiring and runtime are held in:
+
+- `src/app_context.h` (`ReceiverSharedState`)
+
+Public API:
+
+- `ReceiverPipelineConfig`
+- `ReceiverStats`
+- `ReceiverPipeline::begin(...)`
+- `ReceiverPipeline::loop()`
+- `ReceiverPipeline::stats()`
+
+Receiver pipeline owns LoRa RX processing, reassembly/decode, ACK send path, MQTT/SD/display updates, and receiver fault/discovery publication flow.
+
+## HA Manufacturer Single Source
+
+`include/config.h` defines the canonical manufacturer:
+
+- `HA_MANUFACTURER = "AcidBurns"`
+
+Home Assistant discovery payload generation in `src/mqtt_client.cpp` uses this constant directly (`device["manufacturer"] = HA_MANUFACTURER`).
+
+Drift guards:
+
+- compile-time lock in `include/config.h` via `static_assert`,
+- `test/check_ha_manufacturer.ps1` validates discovery assignment and rejects stray hardcoded manufacturer literals in `src/` and `include/`,
+- smoke test `test/test_refactor_smoke/test_refactor_smoke.cpp` asserts the constant value and module header compatibility.