Skip to content

AGENTS.md: require wire-compatible proto changes #189

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

Merged
shawnburke merged 1 commit into from
Nov 10, 2026
+9 −0
Merged

AGENTS.md: require wire-compatible proto changes #189

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
9 changes: 9 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,12 @@ Guidance for AI coding agents working in this repository.
# Architecture notes

- The snyk-broker component is always used in websocket mode. Data transport never uses long polling.

# Protocol compatibility

- Changes under `proto/` MUST be wire compatible in both directions. Tunnel servers and agents are deployed independently and run mixed versions, so existing functionality must never depend on which side is upgraded first.
- Change by adding: new fields, new enum values, new `oneof` members. Never renumber, reuse, or change the type or meaning of an existing field. A field that must be retired stays unused and its number and name are `reserved`.
- A new feature may need both sides to know about it before it lights up. A peer that does not must degrade gracefully: existing behavior continues, and nothing fails, hangs, or tears down the stream.
- Treat a new field's zero value as "the peer didn't say" (e.g. `STAGE_UNSPECIFIED`), never as a meaningful setting.
- Ignore `oneof` members you don't recognize rather than treating them as a protocol error.
- Bound anything that waits on a newer peer (e.g. a grace period), so an older peer that never answers costs latency, not a failure.
Loading