Bootstrap DD3 Rust port workspace with host-first compatibility tests

docs/INTEROP_CHECKLIST.md

@@ -0,0 +1,36 @@
+# Interop Checklist
+
+## A) Rust Receiver <-> C++ Sender
+1. Run C++ sender on `lora-refactor` baseline and Rust receiver host simulation harness.
+2. Verify receiver accepts sender short-id and sender-id mapping.
+3. Verify ACK payload bytes:
+- `[flags:1][batch_id_be:2][epoch_utc_be:4]`
+4. Verify duplicate batch handling:
+- ACK still sent
+- duplicate counters increment
+- publish/log suppressed
+5. Compare MQTT state and fault payload keys/semantics against baseline.
+6. Compare CSV line/header output for shared sample windows.
+
+## B) Rust Sender <-> C++ Receiver
+1. Run Rust sender with sync-request startup behavior.
+2. Confirm C++ receiver decodes payload schema v3 and sparse mask reconstruction.
+3. Confirm ACK mismatch handling does not clear inflight batch.
+4. Confirm retry and catch-up behavior under injected packet loss.
+
+## C) Contract Comparison
+1. Home Assistant discovery topics and payload fields:
+- topic: `homeassistant/sensor/<device_id>/<key>/config`
+- `unique_id`, `device.identifiers`, `device.name`, `device.model`, `device.manufacturer`
+2. MQTT state payload:
+- required keys present
+- legacy keys absent
+3. CSV output:
+- exact header order
+- stable numeric formatting
+
+## D) Port Validation Items
+- Sender unsynced boot sends only sync-requests.
+- ACK bootstrap gate enforced (`time_valid=1` and epoch >= `MIN_ACCEPTED_EPOCH_UTC`).
+- Frame/CRC/ACK/payload golden fixtures all pass.
+- All protocol encode/decode paths covered by fixture-backed tests.

docs/SPEC_LINKS.md

@@ -0,0 +1,36 @@
+# SPEC Links and Constant Extraction
+
+Authoritative behavior spec:
+- https://git.mannheim.ccc.de/C3MA/DD3-LoRa-Bridge-MultiSender/src/branch/lora-refactor/Requirements.md
+
+Pinned baseline commit for fixture provenance:
+- `a3c61f9b929fbc55bfb502b443fba2f98023b3f1`
+
+Primary baseline sources used:
+- `test/test_lora_transport/test_lora_transport.cpp`
+- `test/test_payload_codec/test_payload_codec.cpp`
+- `test/test_json_codec/test_json_codec.cpp`
+- `test/test_html_escape/test_html_escape.cpp`
+- `include/config.h`
+- `src/sender_state_machine.cpp`
+- `src/receiver_pipeline.cpp`
+- `lib/dd3_transport_logic/src/lora_frame_logic.cpp`
+- `lib/dd3_transport_logic/src/batch_reassembly_logic.cpp`
+- `lib/dd3_legacy_core/src/payload_codec.cpp`
+
+Extracted constants locked in this port:
+- `MIN_ACCEPTED_EPOCH_UTC = 1769904000`
+- `SYNC_REQUEST_INTERVAL_MS = 15000`
+- `METER_SAMPLE_INTERVAL_MS = 1000`
+- `METER_SEND_INTERVAL_MS = 30000`
+- `BATCH_MAX_RETRIES = 2`
+- `BATCH_QUEUE_DEPTH = 10`
+- `ACK_REPEAT_COUNT = 3`
+- `ACK_REPEAT_DELAY_MS = 200`
+- `LoraMsgKind::BatchUp = 0`, `LoraMsgKind::AckDown = 1`
+- ACK payload fixed size `7`
+- Home Assistant manufacturer exact string: `AcidBurns`
+
+Fixture provenance:
+- `fixtures/protocol/SOURCES.md`
+- `xtask sync-fixtures` refreshes payload/frame/chunk fixtures.

docs/TEST_STRATEGY.md

@@ -0,0 +1,63 @@
+# Test Strategy
+
+This repository uses four host-side test pillars to preserve compatibility and deterministic behavior.
+
+## 1) Byte-exact protocol compatibility
+- Crate: `dd3_protocol`
+- Scope:
+  - CRC16-CCITT vectors
+  - Frame encode/decode byte identity
+  - ACK payload byte identity
+  - Chunk reassembly deterministic reset semantics
+  - Payload schema v3 decode/re-encode golden vectors
+- Fixtures:
+  - `fixtures/protocol/frames/*.bin`
+  - `fixtures/protocol/chunks/*.bin`
+  - `fixtures/protocol/payload_v3/*.bin`
+
+## 2) Contract stability
+- Crate: `dd3_contracts`
+- Scope:
+  - Home Assistant discovery JSON contract
+  - MQTT state JSON key/semantic stability
+  - CSV header and line format stability
+  - sanitize/html/url behavior including adversarial inputs
+  - manufacturer drift guard
+- Fixtures:
+  - `fixtures/contracts/ha_discovery/*.json`
+  - `fixtures/contracts/mqtt_state/*.json`
+  - `fixtures/contracts/sd_csv/*.csv`
+
+## 3) Deterministic state machine behavior
+- Crates: `dd3_core`, `dd3_sim`
+- Scope:
+  - unsynced sender sync-request cadence
+  - time bootstrap unlock via valid ACK
+  - stop-and-wait retry behavior under loss/backpressure
+  - ACK mismatch handling
+  - duplicate-batch suppression on receiver publish/log paths
+
+## 4) Robustness fuzz/property checks
+- `fuzz/` targets:
+  - `frame_decode`
+  - `chunk_stream_ingest`
+  - `payload_decode_v3`
+  - `sanitize_device_id`
+  - `url_encode_component`
+
+## Running Tests (host only)
+Prerequisite: install Rust toolchain (`rustup`, `cargo`, `rustfmt`, `clippy`).
+
+- Workspace tests:
+  - `make test`
+  - or `cargo test --workspace`
+- Lint:
+  - `make lint`
+- Fuzz smoke (optional, skipped when `cargo-fuzz` missing):
+  - `make fuzz-smoke`
+
+## Fixture Refresh
+- Ensure baseline subtree exists at `vendor/dd3-cpp` pinned to baseline commit.
+- Run:
+  - `cargo run -p xtask -- sync-fixtures`
+  - `cargo run -p xtask -- verify-fixture-sources`