swaitsandClaude Opus 4.6
9db901088e
- CHANGELOG.md: Full audit findings organized by severity - PYMC_CORE_ISSUES.md: 7 evidence-based bug reports for pyMC_core (wrong constants, broken path_len decoding, wrong TRACE hash, wrong SNR calculation) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Add comprehensive spec audit results and pyMC_core issue reports - CHANGELOG.md: Full audit findings organized by severity - PYMC_CORE_ISSUES.md: 7 evidence-based bug reports for pyMC_core (wrong constants, broken path_len decoding, wrong TRACE hash, wrong SNR calculation) - Remove ERRATA.md: contents already covered by audit findings Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# Changelog
|
|
|
|
## 2026-04-01 — Comprehensive Spec Audit
|
|
|
|
### Removed
|
|
|
|
- `ERRATA.md` — Reviewed and removed. Its ACK CRC formula was correct but
|
|
already fully covered by the audit findings (C2). Its claim about ACK routing
|
|
(flood vs tflood) is standard behavior for all packet types (route type is
|
|
always set by the send function, not create), not errata.
|
|
|
|
### Added
|
|
|
|
- `PYMC_CORE_ISSUES.md` — Seven detailed, evidence-based bug reports for the
|
|
pyMC_core Python reference implementation, ready to file as GitHub issues:
|
|
1. `CIPHER_MAC_SIZE` in `constants.py` is 32, should be 2
|
|
2. `MAX_HASH_SIZE` in `constants.py` is 32, should be 8
|
|
3. `MAX_PACKET_PAYLOAD` in `constants.py` is 256, should be 184
|
|
4. `MAX_ADVERT_DATA_SIZE` in `constants.py` is 96, should be 32
|
|
5. `packet.py` `read_from()` treats `path_len` as raw byte count instead of
|
|
decoding hash_size/hash_count bitfield encoding
|
|
6. `packet_utils.py` `calculate_packet_hash()` hashes TRACE `path_len` as 1
|
|
byte instead of 2 (C++ uses `sizeof(uint16_t)`)
|
|
7. `packet_utils.py` `calculate_snr_db()` returns raw value instead of
|
|
dividing by 4.0
|
|
|
|
### Identified (spec issues to fix in future commits)
|
|
|
|
- **Critical errors in spec**:
|
|
- `16-packet-hash.md`: TRACE `path_len` documented as 1-byte hash input, but
|
|
C++ hashes it as `uint16_t` (2 bytes LE)
|
|
- `04-payload-ack.md`: ACK CRC computation described vaguely ("from the
|
|
original message's timestamp, text, and sender public key") — actual
|
|
algorithm is SHA-256 over `(plaintext_data || sender_pub_key)` truncated to
|
|
4 bytes
|
|
- `16-packet-hash.md` / `17-routing.md`: ACK deduplication uses 4-byte CRC
|
|
directly from payload, not the 8-byte packet hash — undocumented
|
|
|
|
- **Major missing documentation**:
|
|
- End-to-end DM data flow (discovery, flood send, path return + ACK, route
|
|
update, switch to direct)
|
|
- Text message plaintext format (`TXT_TYPE_PLAIN=0`, `TXT_TYPE_CLI_DATA=1`,
|
|
`TXT_TYPE_SIGNED_PLAIN=2`), signed message format, ACK computation per type
|
|
- Room server login flow (ANON_REQ with password, login response format,
|
|
connection keepalive at 2.5x timeout)
|
|
- Group/channel message plaintext format (`"sender_name: text"` prefix,
|
|
channel PSK derivation)
|
|
- Remote administration protocol: REQ_TYPE constants (0x01-0x07), status
|
|
response struct, telemetry permissions, CLI-over-mesh via TXT_TYPE_CLI_DATA,
|
|
anonymous request subtypes (REGIONS, OWNER, BASIC/clock sync), neighbour
|
|
queries with sort/pagination
|
|
- Transport codes computation (HMAC-SHA256 based, region key derivation)
|
|
- Duty cycle / airtime budget (formulas, budget factor, refill, enforcement)
|
|
- Retransmit delay formulas (flood random delay, score-based RX delay, CAD
|
|
fail retry)
|
|
- Private key validation (0x00/0xFF rejection, ECDH mutual test, zero-secret
|
|
rejection)
|
|
|
|
- **Moderate issues**:
|
|
- `17-routing.md`: Priority table is misleading — flood forwarding priority is
|
|
dynamic (`hash_count`), not fixed
|
|
- `05-payload-advert.md`: feat1/feat2 only encoded when non-zero (not
|
|
documented)
|
|
- `16-packet-hash.md`: payload_type byte extraction could be clearer (4-bit
|
|
value zero-extended to a byte)
|
|
|
|
- **Companion/KISS/Bridge protocol issues** (lower priority):
|
|
- Companion protocol: spec documents 19 commands, code has 61; framing format
|
|
is wrong (spec says type-byte, code uses `>/<` delimiters with 2-byte LE
|
|
length)
|
|
- KISS: missing default parameter values, CSMA algorithm, RxMeta auto-send
|
|
- Bridge: missing ESP-NOW XOR encryption documentation
|