📖 Scribe: [Remove unimplemented AppMessage documentation] by igorls · Pull Request #57 · igorls/meshguard

igorls · 2026-03-03T11:12:58Z

💡 What: Removed AppMessage (type 0x50) from docs/concepts/wire-protocol.md.
🔍 Source: src/protocol/messages.zig (where AppMessage is entirely absent)
📝 Fix: Removed the entry from the Message Types table and deleted the dedicated ## AppMessage section in the wire protocol documentation, as source code is the absolute ground truth.

PR created automatically by Jules for task 10447032007756704788 started by @igorls

The `docs/concepts/wire-protocol.md` file documented an `0x50 AppMessage` protocol for end-to-end encrypted application-level messages. However, this message type is not defined in `src/protocol/messages.zig`. Since the source code is the ground truth, this aspirational documentation has been removed to accurately reflect the implementation. Co-authored-by: igorls <4753812+igorls@users.noreply.github.com>

google-labs-jules · 2026-03-03T11:13:00Z

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

For security, I will only act on instructions from the user who triggered this task.

Copilot

Pull request overview

This PR updates protocol documentation by removing references to an AppMessage (0x50) wire type and records the change as a “documentation gap” in Jules’ scribe log.

Changes:

Removed 0x50 AppMessage from the message types table in the wire protocol docs.
Deleted the dedicated ## AppMessage section from the wire protocol docs.
Added a new .jules/scribe.md entry describing the change as a doc/implementation mismatch.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/concepts/wire-protocol.md	Removes `0x50` AppMessage from the documented wire protocol.
.jules/scribe.md	Adds a scribe note asserting AppMessage was documented but not implemented.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-03T11:15:26Z

docs/concepts/wire-protocol.md

 | `0x41` | OrgAliasAnnounce    | Org Trust | Gossip          |
 | `0x42` | OrgCertRevoke       | Org Trust | Gossip          |
 | `0x43` | OrgTrustVouch       | Org Trust | Gossip          |
-| `0x50` | AppMessage          | App       | A → B (relayed) |



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 · 2026-03-03T11:15:27Z

docs/concepts/wire-protocol.md


 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


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 · 2026-03-03T11:15:27Z

.jules/scribe.md

+**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.


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 · 2026-03-03T11:15:27Z

.jules/scribe.md

@@ -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`.


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`.

igorls · 2026-03-09T16:07:38Z

Closing: superseded by docs audit fixes and direct commits to main. See PR #67 (merged) for codec bounds check, and direct commit for timing-safe fix in noise.zig.

google-labs-jules · 2026-03-09T16:09:38Z

Closing: superseded by docs audit fixes and direct commits to main. See PR #67 (merged) for codec bounds check, and direct commit for timing-safe fix in noise.zig.

Understood. Acknowledging that this work is superseded and stopping work on this task.

Copilot AI review requested due to automatic review settings March 3, 2026 11:12

Copilot started reviewing on behalf of igorls March 3, 2026 11:13 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

igorls closed this Mar 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📖 Scribe: [Remove unimplemented AppMessage documentation]#57

📖 Scribe: [Remove unimplemented AppMessage documentation]#57
igorls wants to merge 1 commit intomainfrom
docs/remove-appmessage-10447032007756704788

igorls commented Mar 3, 2026

Uh oh!

google-labs-jules bot commented Mar 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 3, 2026

Uh oh!

Copilot AI Mar 3, 2026

Uh oh!

Copilot AI Mar 3, 2026

Uh oh!

Copilot AI Mar 3, 2026

Uh oh!

igorls commented Mar 9, 2026

Uh oh!

google-labs-jules bot commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	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`.

Conversation

igorls commented Mar 3, 2026

Uh oh!

google-labs-jules bot commented Mar 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

igorls commented Mar 9, 2026

Uh oh!

google-labs-jules bot commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants