chore(docs): record JSON-RPC over NATS binding decision (ADR 0011)

[yordis]

• ACP, MCP, and A2A each bind JSON-RPC onto NATS differently today, and the divergence already lets structured errors disappear on some paths; the contract should be settled once rather than per protocol.
• Finalizing the decision now anchors the upcoming shared-binding and signing work before implementation starts.
• ADR cross-references are normalized to relative file links so navigation resolves both in the GitHub view and on the hosted docs site, rather than only one of them.

[cursor]

PR Summary

Low Risk
Documentation-only ADR and link fixes; no runtime or production code changes in this PR.

Overview
ADR 0011 records a single JSON-RPC 2.0 over NATS binding for ACP, MCP, and A2A: a shared binary content-mode codec (jsonrpc-nats) maps method to the subject, authoritative Jsonrpc-* headers (including Jsonrpc-Error-Code for success vs error and Jsonrpc-Id as a JSON literal), and params/result/error bodies—fixing today’s inconsistent mappings and structured-error loss on some ACP paths. It also requires A2A signing to cover those headers, round-trip property tests, edge-only canonical JSON-RPC reconstruction, and a per-subject migration plan starting with authenticate.

Across ADRs 0002–0010 and docs/adr/index.md, intra-ADR references and the records list move from /adr/... site paths to ./000N-....md relative links, and 0011 is listed in the index.

^{Reviewed by Cursor Bugbot for commit a7d84f0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Review limit reached

@yordis, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 43 minutes and 9 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3170d625-ac9b-4fa5-88dd-cde5e37f3457

📥 Commits

Reviewing files that changed from the base of the PR and between 6e1a3dd and a7d84f0.

📒 Files selected for processing (1)

• docs/adr/0011-jsonrpc-over-nats-binding.md

Walkthrough

Existing ADR documents and the ADR index now use relative Markdown links instead of plain-text or absolute /adr/... references. A new ADR 0011 document is added for the JSON-RPC over NATS binding.

Changes

ADR Documentation Updates

Layer / File(s)	Summary
Relative link normalization across existing ADRs and index docs/adr/index.md, docs/adr/0002-rust-crate-boundaries.md, docs/adr/0004-protocol-and-transport-layering.md, docs/adr/0005-polyglot-workspace-layout.md, docs/adr/0006-helpers-naming.md, docs/adr/0008-opentelemetry-observability.md, docs/adr/0009-protocol-buffers-wire-contracts.md, docs/adr/0010-testcontainers-for-infrastructure-tests.md	Plain-text ADR citations and absolute /adr/... link targets are converted to relative ./000x-*.md Markdown links, and the ADR index is rewritten to relative paths while adding ADR 0011.
New ADR 0011: JSON-RPC over NATS binding docs/adr/0011-jsonrpc-over-nats-binding.md	Adds the ADR defining the JSON-RPC 2.0 over NATS binding, including Jsonrpc-* headers, id handling, round-trip invariants, migration steps, consequences, and references.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop-hop, the links are neat,
Relative paths on every sheet.
A new ADR joins the burrow bright,
JSON-RPC over NATS, tucked in right.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: documenting ADR 0011 for the JSON-RPC over NATS binding decision.
Description check	✅ Passed	The description is directly related to the ADR and link-normalization changes in this pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yordis/tripoli

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fd1ef43. Configure here.}

[cursor]

Null request id encoding gap

Medium Severity

§3 maps a missing Jsonrpc-Id on requests to a notification, while §4 and the invariants require decode(encode(m)) for every valid JSON-RPC message. A request that includes "id": null cannot be encoded without colliding with a notification or breaking round-trip fidelity.

Additional Locations (1)

• docs/adr/0011-jsonrpc-over-nats-binding.md#L159-L169

 

^{Reviewed by Cursor Bugbot for commit fd1ef43. Configure here.}