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) 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>
This commit is contained in:
79 files changed
+8923
No files matched your search
@@ -0,0 +1,72 @@
|
||||
# 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
|
||||
Reference in new issue
Block a user