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>
71 lines
2.6 KiB
Markdown
71 lines
2.6 KiB
Markdown
# MeshCore Spec
|
|
|
|
A comprehensive specification and conformance test suite for the
|
|
[MeshCore](https://github.com/meshcore-dev/MeshCore) mesh networking protocol.
|
|
|
|
MeshCore Spec aims to be the authoritative, machine-readable definition of the
|
|
MeshCore wire format — much like [RubySpec](https://github.com/ruby/spec) became
|
|
the definitive specification of the Ruby language. Any implementation that passes
|
|
the full test corpus can claim bit-perfect MeshCore compatibility.
|
|
|
|
## What's Here
|
|
|
|
- **`spec/`** — RFC-style protocol specification in Markdown, covering every
|
|
layer from packet framing to cryptographic operations.
|
|
- **`corpus/`** — JSON test vectors organized by protocol layer.
|
|
Each vector pairs a structured representation with its exact binary encoding,
|
|
enabling any implementation to verify encode and decode correctness.
|
|
- **`tools/`** — Validation and generation utilities.
|
|
|
|
## Test Vector Format
|
|
|
|
Test vectors are JSON files. Binary data is represented as uppercase hex strings
|
|
(whitespace allowed for readability). Each file contains an array of vectors in
|
|
one of three modes:
|
|
|
|
- **`encode_decode`** — Structured input paired with expected binary output.
|
|
Implementations MUST produce the given binary when encoding, and MUST recover
|
|
the given structure when decoding.
|
|
- **`decode_only`** — Binary input with expected structured output. Used for
|
|
alternate valid encodings that an encoder need not produce but a decoder MUST
|
|
accept.
|
|
- **`invalid`** — Binary input that MUST be rejected by a conforming decoder.
|
|
|
|
See `corpus/schema/test-vector.schema.json` for the full schema.
|
|
|
|
## Using the Corpus
|
|
|
|
1. Parse each JSON file in `corpus/`.
|
|
2. For `encode_decode` vectors: encode the `structured` form and compare to
|
|
`binary`; decode `binary` and compare to `structured`.
|
|
3. For `invalid` vectors: attempt to decode `binary` and verify failure.
|
|
|
|
No special tooling is required — just a JSON parser and your MeshCore
|
|
implementation.
|
|
|
|
## Project Status
|
|
|
|
This project is under active development. The specification and corpus are being
|
|
built from the [official MeshCore firmware](https://github.com/meshcore-dev/MeshCore)
|
|
source code.
|
|
|
|
## Protocol Versions
|
|
|
|
The corpus covers all known MeshCore protocol versions. Each test vector file
|
|
includes a `protocol_version` field. Version 1 (the current production version)
|
|
has the most comprehensive coverage.
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## Acknowledgments
|
|
|
|
Based on the [MeshCore firmware](https://github.com/meshcore-dev/MeshCore) by
|
|
the MeshCore developers. Protocol documentation derived from the official
|
|
[MeshCore docs](https://docs.meshcore.io).
|