feat(protocol): read.* surface — typed RPC for history + usage_summary (Phase 2c-2)

[jinhongkuan]

Summary

First in the daemon-as-process arc — full plan in thoughts/shared/plans/2026-05-22-daemon-as-process-arc.md. The arc commits to: daemon is a real process (not a wheel MCP imports); IPC is the only path; tests that verify the boundary spin up a real daemon subprocess.

This PR adds the externally-callable read half of the protocol surface so Phase 2c-4 (the load-bearing first-call-site-migration PR) has concrete RPC targets when it starts rewiring MCP handler bodies through ProtocolClient.

What changed

• protocol/contracts.py — new Pydantic models: HistoryRequest, UsageSummaryRequest, UsageSummaryResult. HistoryResponse stays in contracts.py (shared wire shape between MCP and daemon per the "flat envelopes" preflight constraint).
• protocol/handlers/reads.py — server-side dispatchers. Validate payloads, build a BicameralContext via a single-repo shim (multi-repo lands in 2c-3), delegate to today's handlers.history / handlers.usage_summary code. No MCP handler bodies are modified by this PR.
• tests/test_protocol_read_conformance.py — 6 tests. Dispatch shape + Pydantic input validation + idempotent registration + two constraint tests encoding bicameral-preflight findings:
  • test_read_handlers_have_no_llm_imports — pins the "deterministic read path" constraint (decision:wndwxgam2m8yjor0igya).
  • test_protocol_server_init_does_not_open_db_connection — pins the "lazy ledger connect" constraint (decision:k44cko8xtkcswk55kytz).

Test strategy (per Fowler advisory, 2026-05-22)

In-process loopback only in this PR. The per-test daemon-subprocess fixture lands in 2c-4 alongside the first real call-site migration — build the fixture when there's a call site to test through it, not before.

Compatibility

Pure-additive. MCP server unchanged. End-user MCP tool names (bicameral.history, bicameral.usage_summary) keep working through the today's direct-import path. Nothing in this PR routes through ProtocolClient yet.

Acceptance

• pytest tests/test_protocol_read_conformance.py — 6 passing
• pytest tests/test_protocol_categorization.py + other protocol tests — still green (no regressions)
• ruff check + ruff format --check — both clean
• mypy protocol/ — clean
• CI green on dev

Plan refs

• Arc plan: thoughts/shared/plans/2026-05-22-daemon-as-process-arc.md
• This PR's plan: thoughts/shared/plans/2026-05-22-2c-2-read-surface.md

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cd3c89f8-cc55-4733-92af-84cbafe5c6bb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/daemon-02c-protocol-surface

---

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 and usage tips.}