| 1 | <!-- English translation of adr/0041-protobuf-for-agent-and-ide-messages.md. Canonical Russian: ../../adr/0041-protobuf-for-agent-and-ide-messages.md --> |
| 2 | |
| 3 | # ADR 0041: Protocol Buffers — consideration for agent and IDE messages (entry point) |
| 4 | |
| 5 | **Status:** Proposed (discussion direction and criteria fixed; **not** a decision to migrate from JSON immediately) |
| 6 | **Date:** 2026-04-13 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | MCP contracts and infrastructure | |
| 13 | | [0018](0018-ide-commands-canonical-xml-documentation.md) | `IdeCommands` canon, ProtocolDocGen | |
| 14 | | [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md) | agent facade, tools | |
| 15 | | [0001](0001-debug-hypotheses-json-storage.md) | JSON as chosen storage for a separate domain — do not conflate with this ADR | |
| 16 | |
| 17 | ### Outside ADR |
| 18 | |
| 19 | | Document | Role | |
| 20 | |----------|------| |
| 21 | | [MCP-PROTOCOL.md](../MCP-PROTOCOL.md) | current wire format for IDE commands to the agent | |
| 22 | |
| 23 | --- |
| 24 | ## Context |
| 25 | |
| 26 | Using **Protocol Buffers (protobuf)** instead of or alongside **JSON** for structured messages between **agent**, **IDE**, and related processes has been discussed for a long time. The decision was not fixed in the repo; without an ADR we lose an **entry point** for later discussion and effort estimates. |
| 27 | |
| 28 | This ADR sets a **frame**: where protobuf fits, where JSON remains a reasonable default, which **boundaries** to separate, and which **criteria** to use when deciding — without obligating implementation in a specific product version. |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | ## Problem |
| 33 | |
| 34 | - **JSON** today dominates external protocols (MCP, many LLM APIs), is convenient for **logs, debugging, manual inspection**, and does not require a separate schema/codegen pipeline in simple scenarios. |
| 35 | - **Protobuf** gives **compact representation**, typically **fast** parse/serialize, an **explicit schema** with evolution via field numbers and **.NET** codegen — but adds a **pipeline** (`.proto`, build, version discipline) and is **less human-readable** without tools. |
| 36 | |
| 37 | Without fixed **boundaries** the team risks either rejecting protobuf without criteria, or mixing “internal binary contour” with “external JSON” without explicit policy. |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | <a id="adr0041-p1"></a> |
| 42 | |
| 43 | ## Solution (principles) |
| 44 | |
| 45 | ### 1. Separation by boundary, not “all or nothing” |
| 46 | |
| 47 | - **External / human-readable boundary** (specs like JSON-RPC MCP, public APIs, copy-paste in chats, quick log grep): **JSON** remains the **natural candidate** until spec or ecosystem requires otherwise. |
| 48 | - **Internal high-frequency or high-volume contour** (IPC between IDE processes, event streams, persistent logs of large structures, multiple languages with shared contract): **protobuf** (or other **IDL + binary** format) is a **candidate for evaluation** if measurable benefit outweighs maintenance cost. |
| 49 | |
| 50 | Moving to “protobuf everywhere instead of JSON” is **not** the goal of this ADR. |
| 51 | |
| 52 | <a id="adr0041-p2"></a> |
| 53 | |
| 54 | ### 2. Criteria for deepening protobuf work |
| 55 | |
| 56 | Worth a prototype or RFC if **more than one** of the below holds as a sustained combination on metrics: |
| 57 | |
| 58 | - **Data volume** or **message rate** creates noticeable CPU/IO load vs the rest of the pipeline. |
| 59 | - **Strict schema version compatibility** is needed with parallel client evolution (protobuf field model). |
| 60 | - **Multiple implementations** are planned (e.g. IDE + separate services) and a **single contract** matters without hand-written DTO drift. |
| 61 | |
| 62 | If none apply, **JSON + type discipline** (and contract tests) may remain sufficient. |
| 63 | |
| 64 | <a id="adr0041-p3"></a> |
| 65 | |
| 66 | ### 3. Hybrid |
| 67 | |
| 68 | Often reasonable: **same logical contract** — different codecs on different segments (e.g. JSON on MCP wire and protobuf between internal components), with explicit **mapping** and boundary tests. Not an obligation to duplicate every field by hand forever — but the **conversion point** must be conscious and documented. |
| 69 | |
| 70 | <a id="adr0041-p4"></a> |
| 71 | |
| 72 | ### 4. Relation to current MCP and `IdeCommands` |
| 73 | |
| 74 | While [MCP-PROTOCOL.md](../MCP-PROTOCOL.md) and executor generation describe **JSON arguments** for commands, changing **external** representation for the agent is a **separate** decision (MCP spec, client compatibility). This ADR does **not** cancel current canon; it frames **future** RFCs for internal or optional contours. |
| 75 | |
| 76 | --- |
| 77 | |
| 78 | <a id="adr0041-non-goals"></a> |
| 79 | |
| 80 | ## Non-goals |
| 81 | |
| 82 | - Mandatory migration of all agent exchange to protobuf in the next release. |
| 83 | - Dropping JSON in logs and debug dumps without viewer replacements. |
| 84 | - Binding to a specific gRPC library: protobuf **may** pair with gRPC, but transport choice is separate. |
| 85 | |
| 86 | --- |
| 87 | |
| 88 | <a id="adr0041-open-questions"></a> |
| 89 | |
| 90 | ## Open questions |
| 91 | |
| 92 | 1. Which **concrete streams** in Cascade IDE are first candidates for “JSON vs protobuf” measurement — separate diagram or task after profiling exists. |
| 93 | 2. Whether a **single `.proto` repository** (monorepo + submodules) is needed or only **internal** contracts until API stabilizes. |
| 94 | 3. How to **document** the boundary for contributors: one paragraph in [architecture-policy.md](../architecture-policy.md) vs link only to this ADR. |
| 95 | |
| 96 | --- |
| 97 | |
| 98 | ## Consequences |
| 99 | |
| 100 | - A **stable reference** for discussion and prioritization: “see [0041](0041-protobuf-for-agent-and-ide-messages.md)”. |
| 101 | - Protobuf implementation does **not** follow automatically from Proposed status; a separate decision with metrics or a pilot is required. |
| 102 | |