A contract lab for agent protocol envelopes. Describe an MCP or A2A message shape as a versioned contract, validate real envelopes against it, and classify what changes between revisions as compatible, forward, or breaking.
Agent systems pass structured envelopes between tools and peers: MCP tool calls, A2A task sends, and similar JSON-RPC shaped messages. When the shape of those messages changes, older clients can break in ways that are hard to see until traffic fails. ProtocolArc turns the envelope shape into an explicit, versioned contract so that:
an envelope can be checked against the contract it claims to satisfy,
two revisions of the same contract can be compared to see whether the change is safe, and
a whole set of envelopes and contracts can be cross-checked into one matrix report.
A contract failure and a contract change are treated as different things. A malformed document raises a structural error. A document that parses but does not satisfy a contract produces ordered findings with severities, never an exception.
The compatibility model
diff compares two revisions of the same contract and reports the worst outcome across all field-level changes. One breaking change makes the whole diff breaking.
Verdict
Meaning
compatible
The new revision accepts everything the old one did.
forward
Old consumers keep working; new fields are optional, types widened, constraints relaxed.
breaking
A change can reject previously valid envelopes: a required field added or removed, a type narrowed, an enum restricted, or an optional field tightened to required.
Data model
A contract names a protocol, carries a semantic revision, and lists ordered FieldSpec entries. Each field has a dotted path (params.name), one or more accepted JSON types, a required flag, and an optional enum. A strict contract also flags top-level keys it does not declare.
An envelope declares the contract it targets, an optional revision, and its data body. The bundled fixtures cover both an MCP contract that evolves from 1.0.0 to 2.0.0 and a strict A2A task_send contract.
runtime/ holds ProtocolArc.Runtime, a native validator that mirrors the Python validate logic so a contract checked by either component yields the same findings. It is meant for hot paths where envelopes stream through a gateway.
cd runtime
dotnet run -- selfcheck
dotnet run -- validate ../examples/contracts/mcp_tool_call_1.0.0.json ../examples/fixtures/mcp_calls.jsonl --json
dotnet run -- describe ../examples/contracts/a2a_task_send_1.0.0.json
selfcheck builds a contract and two envelopes in memory and asserts the expected pass and fail split, so CI can confirm the runtime works without external fixtures.
How validation reads an envelope
For each contract field, the validator resolves the dotted path in the envelope body and applies rules in a fixed order:
contract.match: the envelope must target the contract being checked (error).
revision.hint: a declared revision that differs from the contract is a warning, since it may be an older client talking to a newer contract.
field.required: a missing required field is an error.
field.type: a present field must match one of the accepted JSON types.
field.enum: a scalar value must be within the declared enum.
field.unknown: under a strict contract, an undeclared top-level key is a warning.
Findings are sorted by severity, then field, then rule, so the output is stable across runs.
Field ordering is preserved from the contract, and every derived collection is sorted before rendering, so repeated runs over the same inputs produce byte-identical output. Reports come in json, markdown, and text, and each is a pure function of the matrix it renders.
Extending it
Add a validation rule by appending a Finding inside validate_envelope with a rule name, field, severity, and message; the sort key keeps output stable. Add a compatibility rule by extending the CHANGE_IMPACT map in diff.py and emitting the matching Change. Keep the .NET runtime in step with any validation change so both components agree.