meshcore-spec/CHANGELOG.md

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