protocol-rs/CHANGELOG.md

# Changelog

All notable changes to this crate are documented here. The format
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
this project adheres to [Semantic Versioning](https://semver.org/).

## 1.1.0 — 2026-04-22

Spec-only release. No code change in the crate; `PROTOCOL.md`
normative behavior is amended so `SET_CONFIG` no longer disrupts
continuous RX.

### Changed

- `PROTOCOL.md` §3.5 ("Operations Spanning Reconfiguration") and
  §6.3 ("Side effects on `APPLIED`"): a `SET_CONFIG` issued while
  the radio is in continuous RX now **auto-re-arms RX** with the
  new parameters once reconfiguration completes. The RX ring is
  still cleared. The host does **not** need to re-issue `RX_START`
  after `SET_CONFIG`.

  Rationale: the previous "RX is stopped, re-issue RX_START
  yourself" rule was hostile to scanner / time-division /
  dynamic-modulation workflows and violated the principle of least
  surprise. Scope of the change is strictly additive: hosts that
  still issue a redundant `RX_START` after `SET_CONFIG` continue
  to work (firmware replies `OK` with the radio already in
  Receiving).

- No wire-format, field-layout, or `type_id` changes. The CRC, COBS
  framing, tag semantics, and every message shape are byte-for-byte
  identical to 1.0.0.

### Compatibility

- Wire-compatible with 1.0.0 firmware and hosts.
- Behavior-compatible with 1.0.0 hosts (old-style "always re-issue
  RX_START" code paths are now no-ops but still correct).
- New-style hosts that rely on auto-resume **require** firmware
  `donglora 1.1.0` or later, which implements the new semantics.

## 1.0.0 — 2026-04-22

The 1.0 wire-format rewrite. Every message shape, tag-correlation
rule, and field layout is re-specified in the new normative
`PROTOCOL.md` and is incompatible with the 0.1.x line.

### Breaking

- **DongLoRa Protocol v2 wire format.** Every `type_id`, tag-correlation
  rule, and field layout is redefined in `PROTOCOL.md` §2 through §16.
  No byte compatibility with 0.1.x.
- **Module split.** The single-file `lib.rs` is replaced with dedicated
  modules: `frame`, `commands`, `events`, `errors`, `modulation`,
  `info`, `crc`, `chip_id`. Re-exports at the crate root preserve the
  short-form imports (`Command`, `ErrorCode`, etc.), but full paths to
  the old `framing` module and `Response` / `RadioConfig` / `Bandwidth`
  types no longer resolve.
- **Framing replaced.** `src/framing.rs` is gone. The new
  `frame::FrameDecoder` streams inbound bytes and yields
  `FrameResult::Ok { type_id, tag, payload }` on each COBS-delimited,
  CRC-verified frame. Encoding moves to `encode_frame(type_id, tag,
  payload, out)`.
- **`Modulation` replaces `RadioConfig` + `Bandwidth`.** New enum
  covering LoRa, FSK/GFSK, LR-FHSS, and FLRC, each with its own typed
  parameter struct.
- **New response shapes.** `OkPayload`, `SetConfigResult`,
  `TxDonePayload`, `RxPayload`, `RxOrigin`, and `TxFlags` model the
  richer response surface required by v2.

### Added

- `PROTOCOL.md`: the normative specification of DongLoRa Protocol v2,
  including wire examples, error taxonomy, state machine, and
  multi-client semantics (§13).
- `RadioChipId` enum for `GET_INFO` chip identification.
- CRC-16/CCITT-FALSE helper (`crc`) exposed for integrity checks on
  arbitrary payload slices.
- `cap` bitflag helpers on the `Info` struct for decoding capability
  bitmaps.

### Changed

- Fuzz corpus rewritten: `decoder_feed`, `frame_roundtrip`,
  `lora_config_roundtrip`, `parse_command`, `parse_device_message`
  replace the 0.1 `cobs_*` and `command_roundtrip` targets.
- Proptest suite and mutation-killer set expanded to cover the new
  wire shape.
- Canonical-byte vectors rewritten against `PROTOCOL.md` §C.

### CI

- Workflow now runs on pushes to `dev` in addition to `main`.
- Fuzz jobs pinned to `x86_64-unknown-linux-gnu` for reproducibility.

## 0.1.0 — 2026-04-13

Initial release. The DongLoRa wire-protocol types and COBS framing,
extracted from the firmware so the firmware, `client-rs`, `mux-rs`,
and `bridge` can share one definition.

### Added

- Wire types: `Command`, `Response`, `RadioConfig`, `Bandwidth`,
  `ErrorCode`, plus the `MAX_PAYLOAD`, `RADIO_CONFIG_SIZE`,
  `TX_POWER_MAX`, and `PREAMBLE_DEFAULT` constants. Fixed-width
  little-endian on the wire — see the firmware repo's `PROTOCOL.md`.
- `framing` module: streaming `CobsDecoder` plus `cobs_encode_response`,
  with a `MAX_FRAME` constant sized to fit any valid `Response` after
  COBS overhead.
- Cargo features: `defmt` (default, derives `defmt::Format` on public
  enums) and `std` (off, opt-in for host-side `Debug` niceties).
- Test surface: 23 proptest properties (~1.13M cases per run), 4
  cargo-fuzz targets, 16 canonical wire-byte vectors anchored to the
  spec, 6 mutation-killers. Mutation testing reaches 89/89 viable
  mutants under both feature configurations (3 provably-equivalent
  mutants documented and excluded). Miri runs clean on the library
  and the canonical-vector tests.
- `forbid(unsafe_code)` at the crate root.
- GitHub Actions CI (test/clippy/fmt/doc/deny/miri/fuzz/mutants).