Commit Graph
24 Commits
Author SHA1 Message Date
swaits a031c6e266 chore: repoint remaining links at git.swaits.com
mdBook / build (push) Canceled after 0s
mdBook / deploy (push) Canceled after 0s
Rewrites lingering github.com / *.sr.ht references to this Gitea instance,
translating GitHub and Sourcehut URL shapes to Gitea's (/blob/<ref>/ and
sr.ht /tree/<ref>/item/ -> /src/branch/<ref>/, /tree/<tag> -> /src/tag/<tag>,
/actions/workflows/X -> /actions?workflow=X, /edit/ -> /_edit/).

Left pointing at the old hosts on purpose: pull-request links (PRs were not
migrated), forks that were never migrated, and GitHub-only surfaces Gitea
lacks. OpenPGP identity proofs are untouched by design.
2026-08-31 18:32:21 -06:00
swaitsandClaude Opus 4.7 9232c16f7c feat(versioning): snapshot corpus per spec version
mdBook / build (push) Canceled after 0s
mdBook / deploy (push) Canceled after 0s
A frozen spec is only meaningful if it's paired with the corpus
that was current at release time — otherwise a v0.1.0 reader
follows "see corpus/payloads/ack/" and lands on a file whose
test vectors may have changed since v0.1.0 was cut.

Three changes:

1. `cut-version` now copies BOTH src/ AND corpus/ into the
   snapshot directory. A release is the pair, not just the text.

2. The corpus URL rewriting in cut-version now retargets
   /tree/main/corpus -> /tree/main/versions/<v>/corpus (and the
   blob variant). This lets the link resolve on GitHub from main
   alone — no git tag required, since the frozen copy is a real
   path under main. Downgrades the "tag is REQUIRED" message from
   last commit back to "optionally tag the commit".

3. The frozen corpus's spec_ref fields get rewritten too: from
   `src/04-payload-ack.md` to `versions/<v>/04-payload-ack.md`,
   so a reader following a test vector lands on the spec text the
   vector was paired with at release time.

versions/v0.1.0/ regenerated from scratch via `just cut-version v0.1.0`
to pick up the corpus snapshot + the new sed patterns. The release
is now self-consistent: v0.1.0 spec links go to v0.1.0 corpus, which
links back to v0.1.0 spec.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 10:38:02 -06:00
swaitsandClaude Opus 4.7 f83d4088e3 spec: link corpus references to GitHub, version-aware
Every "Test vectors: \`corpus/...\`" mention in the spec is now a
markdown link pointing at the corresponding file or directory on
GitHub. Each version build resolves its links to the correct git
ref:

  - /latest/ -> https://github.com/swaits/meshcore-spec/tree/main/corpus/...
  - /v0.1.0/ -> https://github.com/swaits/meshcore-spec/tree/v0.1.0/corpus/...
  - future /vX.Y.Z/ -> /tree/vX.Y.Z/corpus/...

Two changes:

1. src/*.md (18 files): the inline-code corpus paths in each
   "Cross-References" section are now markdown links. Directories
   point at /tree/main/corpus/..., individual .json files point at
   /blob/main/corpus/.... CHANGELOG and other non-corpus main links
   are intentionally left pointing at main — the canonical history
   lives there regardless of which version you're reading.

2. justfile: `cut-version` now also runs a sed over the snapshot's
   *.md files replacing /tree/main/corpus -> /tree/<VERSION>/corpus
   and /blob/main/corpus -> /blob/<VERSION>/corpus. So a freshly-cut
   version is self-consistent.

versions/v0.1.0/* regenerated by re-running
`just cut-version v0.1.0` after the new src/ links + recipe sed
landed.

Tagging the release commit (`git tag v0.1.0`) is now REQUIRED — not
"optional" — because the rendered /v0.1.0/ pages reference
/tree/v0.1.0/corpus/... on GitHub. Without the tag the links 404.
cut-version's output now says so.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 10:35:09 -06:00
swaitsandClaude Opus 4.7 b6c91505e1 docs: switch author attribution from "Stephen Waits" to SWaits
Per maintainer's preference, the project's outward-facing copy now
refers to the author as [SWaits](https://swaits.com/) instead of
his legal name and email address.

Touched in this commit:
- src/00-overview.md (Status and Provenance callout)
- README.md (Provenance section + Author section; the email
  steve@waits.net is dropped — swaits.com is now the canonical
  contact)
- book.toml (authors = ["SWaits"], plain text since TOML)
- versions/v0.1.0/00-overview.md (regenerated via
  `just cut-version v0.1.0` after src/ was updated)

Git author identity on commit metadata is a separate, git/jj-config
concern and is intentionally not touched.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 10:33:15 -06:00
swaitsandClaude Opus 4.7 9dad83f50b chore(justfile): add preview recipe for local multi-version testing
`just build` produces a single-version site to ./book/ with no
versions.json, and `just build-site` produces the multi-version site
but viewing it via file:// makes the browser block
fetch('versions.json') for security reasons. Both cases leave the
version-picker stuck in label-only mode locally — which looked like
the picker was broken when it was actually doing the right thing
given the available data.

`just preview` is the recipe to test the picker end-to-end:

  1. Runs build-site (full _site/ with versions.json).
  2. Serves _site/ at http://localhost:8000/ via python -m http.server.
  3. Browser fetch() works, picker upgrades to a real dropdown,
     navigation between /latest/ and /v0.X.Y/ works.

Also restructured all recipe doc-comments to single-line summaries
(just --list only shows the immediately-preceding comment, and the
old multi-line comments were rendering as confusing fragments).
Background commentary moved to a file-level header.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 10:27:28 -06:00
swaitsandClaude Opus 4.7 c70ab07c32 feat(mdbook): show spec version in overview body + page title
The first version cut (v0.1.0) revealed a real gap: nothing in the
rendered book identified which release the reader was on. The
version-picker chip says "version: v0.1.0" when you're on /v0.1.0/,
but it's a small UI affordance — and on /latest/ it can't say
"v0.1.0" because /latest/ is the rolling main build, not the v0.1.0
release.

Two complementary fixes, both visible without JS:

1. **Body marker.** Top of every chapter-0 (overview) page now reads
   `Spec version: <token>`. The token is `latest (main)` in src/, and
   gets frozen to the actual version (`v0.1.0`) when cut-version
   snapshots the directory. So /latest/ overview says "latest (main)"
   and /v0.1.0/ overview says "v0.1.0".

2. **Per-build page title.** scripts/build-site.sh now sets
   `MDBOOK_BOOK__TITLE` for each build:
     - latest → "MeshCore Protocol Specification — latest (main)"
     - vX.Y.Z → "MeshCore Protocol Specification — vX.Y.Z"
   The browser tab and mdBook sidebar header reflect the version.

`just cut-version` updated to run a one-line sed on the snapshot's
00-overview.md replacing the `latest (main)` marker. Defensive grep
warns if the marker isn't found (e.g., src/ was edited away from
the expected line).

versions/v0.1.0/00-overview.md regenerated by re-running
`just cut-version v0.1.0` after the marker landed in src/ — so the
v0.1.0 snapshot now self-identifies correctly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 10:22:59 -06:00
swaitsandClaude Opus 4.7 44305a06db release: v0.1.0
First cut release. Snapshots ./src/ as ./versions/v0.1.0/ via
`just cut-version v0.1.0` (22 files: 21 chapter MDs + SUMMARY.md).
Deployed alongside `latest` at:

  https://swaits.github.io/meshcore-spec/v0.1.0/

Also:

- CHANGELOG.md adopts Keep a Changelog-style version sections.
  Future entries land under [Unreleased] and graduate to a version
  heading when cut. The existing date-stamped pass entries stay
  put as a historical record of the work captured in v0.1.0.
- README.md fixes a stale "per vX.Y.Z tag" mention left over from
  the tag-based versioning model, and links the current release
  explicitly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
v0.1.0
2026-05-12 10:04:40 -06:00
swaitsandClaude Opus 4.7 74864761fa feat(mdbook): switch versioning from git tags to versions/ directories
Replace the git-tag-based snapshot model with frozen-directory
snapshots. Each released spec version is its own subtree under
./versions/vX.Y.Z/ — a literal copy of ./src/ taken at release time.

Why: tagging the whole repo conflated *spec content* with *site
infrastructure* (book.toml, theme, picker JS, workflow, build
scripts). Improving any of those required cherry-picking the change
back to every old tag. With directory snapshots, content is frozen
but every deploy renders every version with TODAY's infrastructure
— site fixes propagate everywhere for free.

Changes:

- scripts/build-site.sh now iterates ./versions/v* directories
  instead of `git tag --list 'v*'`. Each per-version build sets
  MDBOOK_BOOK__SRC to the snapshot dir and MDBOOK_OUTPUT__HTML__SITE_URL
  to /meshcore-spec/<version>/. The root book.toml, theme, and
  picker JS apply uniformly.
- justfile gains `cut-version vX.Y.Z` — validates the name, refuses
  to overwrite, runs `cp -R src versions/<version>`, prints next-
  step hints. Cutting a release is now `just cut-version v0.1.0`,
  then a commit; optionally tag the commit for provenance, but
  tags no longer drive CI.
- .github/workflows/mdbook.yml drops the `tags: ['v*']` trigger
  and `fetch-depth: 0` (no longer iterating git history). Triggers
  on push to main and PRs.
- src/00-overview.md: "Spec Versions" section rewritten to describe
  the directory-snapshot model and the deliberate content-vs-
  infrastructure split.

Smoke-tested locally: `just build-site` with no versions/ produces
`_site/{latest/, versions.json=["latest"], index.html}`.
`just cut-version v0.0.1` + rebuild produces both `latest/` and
`v0.0.1/`, versions.json=`["latest","v0.0.1"]`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 10:03:46 -06:00
swaitsandClaude Opus 4.7 da00e46570 feat(mdbook): version-picker always renders a label
Previously the picker silently hid when the URL didn't contain a
/<version>/ segment — which is exactly the case for `just build`
opened via file://. The reader saw no version indicator at all.

Now the picker always mounts a "version: latest" label first
(immediately, before any fetch). When a versions.json is reachable
AND we have a real version segment in the URL (so navigation is
computable), the label upgrades into the existing dropdown. On
file:// or single-version sites the static label stays.

CSS gains styling for the static "version: <name>" name span.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:57:54 -06:00
swaitsandClaude Opus 4.7 fd75d297ca ci(mdbook): drive CI through mise + just (no inline shell)
CI now mirrors the local dev path. The workflow installs mise,
trusts the config, installs all mise-pinned tools (mdbook, just),
and invokes `just build-site` for the whole multi-version build.
There is no longer any build logic inside the workflow YAML.

Changes:

- `mise.toml` now also pins `just = "1.50.0"` so `mise install`
  brings in both mdbook and just.
- `scripts/build-site.sh` (new, POSIX sh, shellcheck-clean) takes
  the multi-version build loop out of the workflow and parks it
  next to the rest of the build tooling. Iterates v* tags via
  `git worktree`, sets `MDBOOK_OUTPUT__HTML__SITE_URL` per
  version, emits `_site/versions.json` and `_site/index.html`
  (root redirect to /latest/).
- `justfile` gains a `build-site` recipe — `sh scripts/build-site.sh`.
- `.github/workflows/mdbook.yml` is now four short steps inside
  the build job: jdx/mise-action (install: false) → `mise trust`
  → `mise install` → `just build-site`. The previous inline
  multi-line bash block is gone.
- `.gitignore` adds `/_site/` alongside the existing `/book/`.

Local smoke test: `just build-site` with no v* tags produces
`_site/{latest/, versions.json=["latest"], index.html}` exactly as
CI will. Future `v0.1.0` tag will add `_site/v0.1.0/` and update
`versions.json` without any code changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:56:25 -06:00
swaitsandClaude Opus 4.7 9ad31f7470 feat(mdbook): multi-version site, mise-pinned tools, justfile
Three intertwined changes — split conceptually but landed together
because they share the same workflow rewrite:

1. MULTI-VERSION SITE. The published site now keeps every prior spec
   version alongside the rolling latest build (docs.rs / readthedocs
   pattern):

   - .github/workflows/mdbook.yml builds latest from current HEAD and
     each v* tag in a git worktree, placing each into _site/<ver>/.
     Each per-version build gets MDBOOK_OUTPUT__HTML__SITE_URL set to
     /meshcore-spec/<ver>/ so the sitemap/canonical links resolve
     correctly per version.
   - Workflow emits _site/versions.json (newest first) and a root
     index.html that redirects to /latest/.
   - theme/version-picker.js is a small client-side dropdown that
     fetches /<base>/versions.json and lets the reader switch to the
     same chapter in any other version. Slots into mdbook's menu bar
     (.right-buttons); falls back to a fixed top-right widget if the
     menu isn't found.
   - theme/version-picker.css styles it to fit the navy theme.
   - book.toml wires the picker files via additional-js /
     additional-css; site-url defaults to /meshcore-spec/latest/ for
     the main build (CI overrides per tag).
   - Old tags built without these files render without a picker, which
     is fine — users won't typically need to navigate AWAY from an
     older version. v0.1.0 onward will all carry the picker.

   Spec versions use independent semver and do NOT mirror MeshCore
   firmware versions; each spec release records the upstream commit
   hash it was validated against in CHANGELOG.md.

2. MISE-PINNED TOOLS. mise.toml pins cargo:mdbook so local dev and
   CI use the same version. The workflow installs everything via
   jdx/mise-action instead of peaceiris/actions-mdbook, making
   mise.toml the single source of truth for tool versions.

3. JUSTFILE. justfile gives short names (build / serve / clean /
   validate / setup) for the common tasks. Recipes run under
   `mise exec -- sh -c …` so they always pick up the mise-pinned
   tools (sh is intentional, keeping recipes POSIX-compatible).

Documentation: README's spec link now mentions the versioning model;
src/00-overview.md gets a "Spec Versions" subsection explaining the
URL layout and version-picker.

Verified locally: `just build` produces a clean book/ with the
version-picker JS/CSS injected (hashed filenames, slotted into
theme/). JS parses clean under `node --check`.

Note for first-time deploy: GitHub Pages source must be set to
"GitHub Actions" in repo settings (one-time, manual). After that,
push to main builds + deploys latest, and pushing a v* tag adds
the snapshot to the site.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:51:07 -06:00
swaitsandClaude Opus 4.7 4d6f31d152 spec(overview): add prominent unofficial/AI-authored provenance callout
The book's first page previously claimed the spec was "the
authoritative definition of the wire format" derived from the
firmware. That misrepresents the project's stance. Replace the
existing "Status" block with a more honest "Status and Provenance"
block that mirrors the README disclosure:

- This is an unofficial, independent project — NOT part of the
  upstream MeshCore project, not affiliated, not endorsed.
- Primarily AI-authored (Claude / Opus 4.x) under Stephen Waits's
  direction, with human proofreading and editing.
- The upstream MeshCore C++ firmware is the source of truth;
  this spec is downstream. CHANGELOG records the upstream commit
  hash per pass.
- DongLoRa observations refine the spec but never override
  upstream.
- The corpus is a useful signal but not a substitute for
  cross-checking against upstream firmware.

Visible to anyone landing on https://swaits.github.io/meshcore-spec/
or reading the rendered overview chapter.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:43:18 -06:00
swaitsandClaude Opus 4.7 d785e35919 feat(mdbook): publish spec via mdBook on GitHub Pages
Set up the protocol spec as an mdBook and add a GitHub Actions
workflow that builds it on every push/PR and deploys to GitHub
Pages on main. The repo is now both a machine-readable corpus and
a browsable, searchable site.

Structure changes (one-time, mechanical):

- Rename the spec source directory from `spec/` to `src/` to match
  mdBook's default convention. All 21 chapter files move; their
  internal relative cross-links are unchanged.
- Add `src/SUMMARY.md` as the mdBook table of contents, grouping
  chapters under Wire Format, Payloads, Cryptography & Identity,
  and Routing & Higher-Layer Protocols.
- Add `book.toml` at repo root: title, author, search enabled,
  fold enabled, edit-on-GitHub links, navy theme.
- Add `.github/workflows/mdbook.yml`: build on push + PR, deploy
  on push to main only (configure-pages + upload-pages-artifact +
  deploy-pages from actions/).
- Add `/book/` to .gitignore.

Reference updates so the old path is fully retired:

- Every `spec_ref` in `corpus/**/*.json` rewritten from `spec/` to
  `src/` (54 files).
- Schema description text and example path in
  `corpus/schema/test-vector.schema.json`.
- `README.md`: prominent link to the published site near the top;
  "What's Here" updated for the new layout.
- `CONTRIBUTING.md`: spec-editing instructions point at `src/`
  and note the SUMMARY.md requirement.
- `CLAUDE.md`: directory-layout notes updated.

CHANGELOG.md historical entries intentionally keep their `spec/`
paths since those record what the paths were at the time of those
commits.

After this lands, the user needs to enable GitHub Pages in repo
settings with source = "GitHub Actions" (one-time, manual). The
workflow will then publish to https://swaits.github.io/meshcore-spec/
on every push to main.

Verified locally: `mdbook build` produces a clean book/ tree with
all 21 chapters rendered and the SUMMARY-driven sidebar populated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:36:28 -06:00
swaitsandClaude Opus 4.7 75fb228909 docs(changelog): add 2026-05-12 publication-readiness entry
Record this pass at the top of CHANGELOG.md:

- Upstream baseline: meshcore-dev/MeshCore @ 1a7b361 (2026-04-28).
  Every normative claim was cross-checked against this commit.
- Process: adopted conventional commits; established
  "upstream-firmware-is-the-golden-source-of-truth" as a load-bearing
  principle for the project.
- Added: ack-crc test vectors; explicit ACK CRC algorithm; attempt
  semantics including tail-byte encoding for attempt > 3; reliable
  DM delivery; multipart direct-only and finalizer plain-ACK;
  sender-behavior/transmission-priority section in routing; README
  provenance + Author.
- Clarified: AES plaintext zero-padding scheme; MULTIPART chain
  descending count + plain finalizer.
- Corrected: 17-routing previously misrepresented upstream's
  path-replacement as a hash-size/SNR heuristic; upstream actually
  replaces unconditionally.
- Out of scope: ai-bot-specific values (route TTL, SNR margin,
  1-byte hash rejection, 150ms PATH_RETURN, 0x1424 sync word,
  pending-ACK 64/125s) were considered and dropped since they are
  not upstream behavior. Radio/hardware-state firmware items also
  excluded as out of protocol scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:27:07 -06:00
swaitsandClaude Opus 4.7 4a13c12ee9 docs(readme): add prominent Provenance disclosure and Author section
Prepare the repo for public release by stating openly:

- The spec is AI-authored (Claude / Anthropic) under Stephen Waits's
  direction. It is an independent project, not affiliated with the
  upstream MeshCore project.
- The official MeshCore C++ firmware is the golden source of truth for
  all protocol behavior; when this spec and upstream disagree, upstream
  wins.
- Clarifications have been driven by observations from building
  DongLoRa firmware and apps against live deployments, but DongLoRa
  divergences from upstream are treated as DongLoRa bugs, not spec
  changes.
- Conformance against this corpus is a useful signal but not a
  substitute for cross-checking against upstream.

Tighten Project Status to reference the new section. Add an Author
section with attribution.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:26:28 -06:00
swaitsandClaude Opus 4.7 ac581fccda spec(routing): align path-learning with upstream and document PATH_RETURN delay
Two changes:

1. CORRECTION. The path-learning subsection previously described the
   reference implementation's path-replacement as "replace only if
   the new path's hash size is not smaller and SNR is not materially
   worse" — but upstream's BaseChatMesh::onContactPathRecv() does an
   UNCONDITIONAL replace, with an inline comment flagging hash-size/
   SNR selection as future work. The spec now reflects upstream's
   actual behavior and notes that quality heuristics are an
   implementation extension, not a reference-implementation behavior.
   Likewise, removed the implication that the reference implementation
   has a cached-path TTL — it doesn't.

2. ADDITION. Document PATH_RETURN scheduling delay
   (TXT_ACK_DELAY=200ms default in upstream BaseChatMesh.cpp:9), with
   the rationale of spacing PATH_RETURN, ACK, and reply across
   distinct slots.

Validated against upstream meshcore-dev/MeshCore @ 1a7b361
(BaseChatMesh.cpp:304-307 unconditional replace; cpp:228, 255
TXT_ACK_DELAY-spaced PATH_RETURN emission).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:25:50 -06:00
swaitsandClaude Opus 4.7 3a8918fb0e spec(multipart): document plain-ACK finalizer after MULTIPART chain
Clarify that the MULTIPART ACK chain terminates with a plain
PAYLOAD_TYPE_ACK (not a MULTIPART with remaining=0). For K extra
copies, the wire sequence is:

  MULTIPART(remaining=K), MULTIPART(remaining=K-1), ...,
  MULTIPART(remaining=1), then PAYLOAD_TYPE_ACK (plain).

All copies share the same ack_crc. Receivers MUST dedup at the
application layer by ack_crc, since each packet's hash differs.

Validated against upstream meshcore-dev/MeshCore @ 1a7b361
(Mesh::routeDirectRecvAcks, src/Mesh.cpp:362 — while-loop emits
MULTIPART(remaining=extra...1), then createAck(crc) plain ACK).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:25:19 -06:00
swaitsandClaude Opus 4.7 c0f9c22efd spec(encrypted): clarify zero-padding scheme for AES plaintext
Tighten the encryption steps to spell out:

- Plaintext is zero-padded on the right to a multiple of 16 bytes
  before AES-128-ECB encryption.
- The padding is NOT PKCS#7 (not unambiguous); the receiver must
  disambiguate trailing zeros using the inner plaintext format
  (e.g., for TXT_MSG, by C-string NUL termination scan).
- Renumber steps so the padding step is explicit and ordered before
  encryption, instead of being a parenthetical on the encrypt step.

Validated against upstream meshcore-dev/MeshCore @ 1a7b361
(Utils::encrypt / Utils::decrypt, src/Utils.cpp:30-, comment
"dest may contain trailing zero bytes in final block").

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:25:05 -06:00
swaitsandClaude Opus 4.7 4095fc91c7 spec(routing): add sender behavior and transmission priority
Add a "Sender Behavior (Informational)" section to Section 17 that
captures the cross-implementation conventions for how senders should
behave above the wire format:

- Path Learning: cache the reversed accumulated path from received
  flood-routed packets; replace only when the new path is at least as
  good (hash size, SNR threshold implementation-defined).
- PATH_RETURN: proactive emission lets the original sender switch to
  direct routing without waiting for an explicit path probe.
- Flood Fallback and Retries: track outstanding DMs by expected
  ack_crc, increment attempt on each retry, hold timestamp constant,
  fall back from direct to flood after N unacknowledged direct
  retries.
- Transmission Priority (sender-originated) table: ACK > PATH >
  direct reply > flood reply > req/resp > group > advert.

All of these are informational guidance; numeric tunings remain
implementation-defined. Complements the existing forwarding-priority
table.

Validated against upstream meshcore-dev/MeshCore @ 1a7b361
(BaseChatMesh send/recv flow, Mesh::createPathReturn,
handleReturnPathRetry).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:23:12 -06:00
swaitsandClaude Opus 4.7 1c2007dcb5 spec(multipart): constrain MULTIPART ACK to direct paths
Add a "Multipart ACK Usage Constraints" subsection making explicit
what upstream enforces in code but the spec previously left implicit:

- MULTIPART-wrapped ACKs MUST only be emitted on direct-routed return
  paths. When no direct path is known, the sender MUST fall back to a
  plain PAYLOAD_TYPE_ACK via flood. Matches sendAckTo() and
  routeDirectRecvAcks() in upstream.
- All MULTIPART and plain copies of the same ACK carry an identical
  4-byte ack_crc; receivers MUST dedup by CRC at the application
  layer (Section 16 packet-hash dedup does not catch them because the
  wrapper byte makes each copy hash-distinct).
- Typical inter-copy delay ~300 ms plus the direct retransmit delay;
  exact count via getExtraAckTransmitCount() (reference default 0).

Validated against upstream meshcore-dev/MeshCore @ 1a7b361
(Mesh::routeDirectRecvAcks, BaseChatMesh::sendAckTo).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:23:04 -06:00
swaitsandClaude Opus 4.7 ce358996ad spec(encrypted): clarify attempt semantics and reliable DM delivery
Two additions to the TXT_MSG section:

1. Attempt Counter Semantics. Spells out that bits 0-1 of
   txt_type_attempt carry attempt & 3, the input the ACK CRC depends
   on. For attempt > 3, upstream appends a [NUL][attempt_full] tail
   after the text (BaseChatMesh.cpp:410-412), recovering the full
   attempt value at the cost of 2 bytes of text capacity. The tail is
   NOT part of the ACK CRC input, so attempt=4 and attempt=0 collide
   on CRC and senders relying on >3 must verify the trailing byte.

2. Reliable DM Delivery. Documents the sender-side ACK tracking
   contract: maintain a pending-ACK table keyed by expected CRC,
   retry with attempt incremented, consume MULTIPART-wrapped or plain
   ACKs identically, and the receive-side option to cache replies per
   peer for duplicate-DM loss recovery.

Validated against upstream meshcore-dev/MeshCore @ 1a7b361
(BaseChatMesh::composeMsgPacket, onPeerDataRecv TXT_MSG handling).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:22:56 -06:00
swaitsandClaude Opus 4.7 277d4463c1 spec(ack): document explicit ACK CRC computation algorithm
Spell out the SHA-256-truncation algorithm previously described in
prose:

  ack_crc = SHA-256(plaintext_prefix || sender_pub_key)[0..3]

where plaintext_prefix = timestamp(4) || txt_type_attempt(1) || text
(excluding any trailing NUL terminator). Add the SIGNED_PLAIN variant
(includes 4-byte signature prefix, hashes against receiver's pub_key).
Reference the upstream functions that implement each side.

Resolves the ACK CRC vagueness called out in the 2026-04-01 audit.
Paired with the new corpus/crypto/sha256/ack-crc.json vectors.

Validated against upstream meshcore-dev/MeshCore @ 1a7b361
(BaseChatMesh.cpp:222, 249, 407; Utils::sha256 two-fragment form).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:22:48 -06:00
swaitsandClaude Opus 4.7 2cf3d29fe1 corpus(crypto): add ack-crc test vectors
Add four SHA-256-truncation vectors covering ACK CRC computation with
incrementing attempt values (0..3) over a stable (timestamp, text,
sender_pub_key) triple. Demonstrates that each retry produces a
distinct expected CRC, fixing the algorithmic ambiguity noted in the
2026-04-01 audit.

Algorithm: SHA-256(timestamp(4) || txt_type_attempt(1) || text ||
sender_pub_key(32))[0..3] as little-endian uint32.

Validated against upstream meshcore-dev/MeshCore @ 1a7b361
(BaseChatMesh::composeMsgPacket, src/helpers/BaseChatMesh.cpp:407).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 09:22:41 -06:00
swaitsandClaude Opus 4.6 9db901088e 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>
2026-04-01 21:37:57 -06:00