Skip to content

📖 Scribe: [Remove unimplemented AppMessage documentation] #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
igorls wants to merge 1 commit into from
Closed

📖 Scribe: [Remove unimplemented AppMessage documentation] #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .jules/scribe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,7 @@
**Gap:** The documentation stated the SWIM protocol period was 1000ms (1s), but the implementation uses 5000ms (5s) in both `src/config.zig` and `src/discovery/swim.zig`.
**Learning:** The documentation likely reflected an early design decision or standard SWIM defaults, but the implementation settled on a more conservative 5s interval for WAN stability, and docs were not updated.
**Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Markdown convention in this file separates each ## section with a blank line (see the headers at lines 6 and 11). Add a blank line before the new ## 2024-03-22 - AppMessage Documentation Gap header to keep formatting consistent and improve readability.

Suggested change
**Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.
**Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.

Copilot uses AI. Check for mistakes.
## 2024-03-22 - AppMessage Documentation Gap
**Gap:** The documentation (docs/concepts/wire-protocol.md) described an AppMessage protocol for end-to-end encrypted application-level messages, while the implementation (src/protocol/messages.zig) does not define it.
**Learning:** Documentation drifted because the initial design likely included an AppMessage protocol which was either not implemented or removed, but docs were not updated.
**Prevention:** Regularly audit messages.zig against documentation to ensure all documented message types are actually defined.
Comment on lines +16 to +18
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new entry states the implementation does not define AppMessage, but the codebase does implement 0x50 app messages (e.g. src/discovery/swim.zig and src/meshguard_ffi.zig). Please update this scribe note to reflect the actual gap (e.g., AppMessage is implemented but is special-cased outside messages.zig/codec.zig, or was documented differently than the current behavior).

Suggested change
**Gap:** The documentation (docs/concepts/wire-protocol.md) described an AppMessage protocol for end-to-end encrypted application-level messages, while the implementation (src/protocol/messages.zig) does not define it.
**Learning:** Documentation drifted because the initial design likely included an AppMessage protocol which was either not implemented or removed, but docs were not updated.
**Prevention:** Regularly audit messages.zig against documentation to ensure all documented message types are actually defined.
**Gap:** The documentation (`docs/concepts/wire-protocol.md`) described an AppMessage protocol for end-to-end encrypted application-level messages, and this scribe entry originally claimed the implementation did not define AppMessage at all. In reality, `0x50` AppMessage frames are implemented but are special-cased in `src/discovery/swim.zig` and `src/meshguard_ffi.zig` rather than going through `src/protocol/messages.zig`/`codec.zig`, and the docs do not reflect this split behavior.
**Learning:** Documentation and internal notes drifted from the actual implementation path: they assumed AppMessage would either be defined in `messages.zig` or not implemented, but the final design routes `0x50` messages through SWIM/FFI helpers instead of the central message codec.
**Prevention:** When a wire message type is handled outside `messages.zig`/`codec.zig`, explicitly call that out in `docs/concepts/wire-protocol.md` and in this scribe, and extend audits to include all modules that originate or consume wire messages (e.g., discovery and FFI code), not just `messages.zig`.

Copilot uses AI. Check for mistakes.
16 changes: 0 additions & 16 deletions docs/concepts/wire-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,6 @@ SWIM messages use a **1-byte type tag**:
| `0x41` | OrgAliasAnnounce | Org Trust | Gossip |
| `0x42` | OrgCertRevoke | Org Trust | Gossip |
| `0x43` | OrgTrustVouch | Org Trust | Gossip |
| `0x50` | AppMessage | App | A → B (relayed) |

Comment on lines 33 to 36
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description says AppMessage is unimplemented because it’s absent from src/protocol/messages.zig, but the implementation still handles raw 0x50 app messages (e.g. src/discovery/swim.zig special-cases data[0] == 0x50 and relays/delivers them, and src/meshguard_ffi.zig builds/parses the same wire format). Removing 0x50 from the message-types table makes the wire-protocol docs inaccurate; consider keeping it documented (possibly clarifying it bypasses the SWIM codec).

Copilot uses AI. Check for mistakes.
## Ping

Expand Down Expand Up @@ -150,21 +149,6 @@ Propagated via gossip. Org admin vouches for an external standalone node — all

Total: **137 bytes**. Signature covers `vouched_pubkey ‖ lamport`. Revocable via OrgCertRevoke.

## AppMessage

End-to-end encrypted application-level message, relayed through the mesh.

```
[0x50][32B dest_pubkey][32B sender_pubkey][12B nonce][N ciphertext][16B tag]
```

Minimum size: **93 bytes** (empty payload). Maximum payload: 1024 bytes.

- **Key derivation**: X25519(sender_private, dest_wg_pubkey) → HKDF("meshguard-app-v1") → symmetric key
- **AD**: sender's Ed25519 public key
- **Routing**: intermediate peers forward the entire packet as-is (encrypted, opaque) to the destination by pubkey lookup
- **Delivery**: when `dest_pubkey` matches our own, the message is decrypted and delivered via callback

## Endpoint Encoding
Comment on lines 149 to 152
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AppMessage (0x50) appears to be implemented and in use (handled directly in src/discovery/swim.zig and decrypted/enqueued in src/meshguard_ffi.zig). Deleting this section removes the only documentation of the 0x50 wire format; unless the protocol is being removed from code, this section should remain (or be replaced with updated text that matches the current implementation path, since it’s not part of codec.decode).

Copilot uses AI. Check for mistakes.

All IPv4 endpoints are encoded as:
Expand Down