diff --git a/docs/ADR-110-BRANCH-STATE.md b/docs/ADR-110-BRANCH-STATE.md new file mode 100644 index 00000000..d2504ebe --- /dev/null +++ b/docs/ADR-110-BRANCH-STATE.md @@ -0,0 +1,84 @@ +# ADR-110 — Branch state (as of 2026-05-23, iter 22) + +Reference card for anyone collaborating on or near the ADR-110 work. The /loop SOTA sprint that closed the firmware-side substrate ran into multiple cross-branch checkout incidents (see iter 17-19); this page exists so the next collaborator doesn't have to re-derive the layout from `git log`. + +## Branch ownership + +| Branch | Owner | What it carries | Don't merge from | +|---|---|---|---| +| `main` | shared | shipped release line | — | +| `adr-110-esp32c6` | ADR-110 / C6 firmware substrate | Everything described in `WITNESS-LOG-110 §A0.x` (4 firmware tags v0.6.7 → v0.7.0, Python + Rust decoders, sensing-server wire, mesh-aligned timestamp recovery, fps EMA, cross-language conformance gate) | Don't accidentally land `feat/adr-115-ha-mqtt-matter` work here uncommitted | +| `feat/adr-115-ha-mqtt-matter` | ADR-115 / HA-DISCO + HA-FABRIC + HA-MIND | MQTT publisher (`rumqttc`), Matter Bridge, semantic automation primitives, related Cargo features + CLI flags | Don't accidentally land ADR-110 `wifi-densepose-hardware` dep mods here | + +## Files each branch touches + +### `adr-110-esp32c6` — primary modifications + +``` +firmware/esp32-csi-node/version.txt # bumped 0.6.6 → 0.7.0 +firmware/esp32-csi-node/main/c6_*.{c,h} # LP-core, TWT, timesync, soft-AP HE, ESP-NOW sync +firmware/esp32-csi-node/main/lp_core/main.c # real LP-core polling program +firmware/esp32-csi-node/main/csi_collector.c # byte 19 bit 4 OR-fix; sync packet emit +firmware/esp32-csi-node/main/Kconfig.projbuild # C6_* knobs +firmware/esp32-csi-node/main/CMakeLists.txt # ulp_embed_binary +firmware/esp32-csi-node/sdkconfig.defaults.esp32c6 # C6 overlay + +archive/v1/src/hardware/csi_extractor.py # SyncPacketParser + SyncPacket dataclass +archive/v1/tests/unit/test_esp32_binary_parser.py # TestSyncPacketParser (7 tests) + +v2/crates/wifi-densepose-hardware/src/sync_packet.rs # new module (15 tests) +v2/crates/wifi-densepose-hardware/src/lib.rs # re-exports +v2/crates/wifi-densepose-sensing-server/Cargo.toml # ONLY adds wifi-densepose-hardware path dep +v2/crates/wifi-densepose-sensing-server/src/main.rs # NodeState::{latest_sync, csi_fps_ema, + # mesh_aligned_us_for_csi_frame, + # observe_csi_frame_arrival} + # udp_receiver_task magic dispatch + # fps_ema_tests module (4 tests) + +docs/adr/ADR-110-esp32-c6-firmware-extension.md # 670 → ~750 lines (P10 + sprint summary) +docs/WITNESS-LOG-110.md # 13 §A0.x entries +docs/ADR-110-REVIEW-GUIDE.md # reviewer one-pager +docs/ADR-110-BRANCH-STATE.md # ← this file +``` + +### `feat/adr-115-ha-mqtt-matter` — primary modifications + +``` +docs/adr/ADR-115-home-assistant-integration.md # the design +v2/crates/wifi-densepose-sensing-server/Cargo.toml # rumqttc dep + [features] block +v2/crates/wifi-densepose-sensing-server/src/cli.rs # --mqtt / --matter / --semantic flags +``` + +## Known overlap points (handle with care) + +Both branches touch `v2/crates/wifi-densepose-sensing-server/Cargo.toml` and `src/main.rs`. The conflict surface is **disjoint by section**: + +| File | ADR-110 region | ADR-115 region | +|---|---|---| +| `Cargo.toml` | `[dependencies]` — `wifi-densepose-hardware = { path = "../wifi-densepose-hardware" }` near the existing `wifi-densepose-signal` line | `[dependencies]` — `rumqttc` block below + `[features]` block at end | +| `main.rs` | `NodeState` fields + `impl NodeState` helpers + `update_csi_fps_ema` free fn + `fps_ema_tests` module + `udp_receiver_task` magic dispatch | (TBD per ADR-115 P-plan) | + +A merge between the two branches should be **clean line-merge** since the regions don't overlap. If git ever reports a real conflict in either of these files, that means one branch has drifted into the other's region — investigate before resolving blindly. + +## Quick test commands (verify either branch is sane) + +```bash +# Rust workspace (run from v2/) +cd v2 +cargo test --workspace --no-default-features --lib # 1437 tests at iter 22, 0 failures + +# Python ADR-110 host decoder (from repo root) +python -m pytest archive/v1/tests/unit/test_esp32_binary_parser.py::TestSyncPacketParser -v + +# Cross-language wire-format gate (the iter 21 pin) +cargo test -p wifi-densepose-hardware --no-default-features --lib sync_packet::tests::canonical_wire_bytes_match_python_decoder +python -m pytest archive/v1/tests/unit/test_esp32_binary_parser.py::TestSyncPacketParser::test_canonical_wire_bytes_match_rust_decoder -v +``` + +If either side of the canonical-wire-bytes pair fails alone, the OTHER decoder has drifted from the wire format — investigate that decoder first, not the failing test. + +## Future-proofing + +- When the ADR-115 agent ships `feat/adr-115-ha-mqtt-matter` to main and ADR-110 also ships, merge `main` into `adr-110-esp32c6` (or vice versa) and re-run both test suites. The disjoint-region structure above should make the merge a no-conflict fast-forward. +- When a third agent picks up either ADR, point them at this file before they start editing shared files. +- If a /loop drives autonomous iterations and hits a cross-branch checkout, the recovery procedure is in iter 18's commit message (`2997165bc`) — stash on the foreign branch, `git checkout` home, replay the iter locally.