docs(tbtc/signer): Phase 7.0 sidecar transport addendum

[mswilkison]

What

The outstanding 7.0 item from the frozen Phase 7 spec (§9): maps the frozen §5 session API onto the sidecar process boundary (Decision Log entry 2) and scopes #4007's TEE checker stack against it. Doc-only; by construction it changes no contract — anything in it that would alter the frozen spec is a defect in the addendum.

Highlights

• The swap was pre-paid: the coarse JSON request/response contract was chosen over round-level FFI partly for sidecar extraction, and the frozen spec's engine-held nonce custody dissolves the old brief's objection to round-level APIs — rounds cross the boundary, nonces never do.
• Decision 7 carries over unchanged: with TBTC_SIGNER_INIT_CONFIG_PATH set, a sidecar that can't spawn, can't handshake, or rejects the config is process-fatal for the host — "sidecar unreachable" joins the existing fatal failure family at the same enforcement point.
• Crash = the restart story we already ratified: markers-only durability means a sidecar crash fails live attempts safe, consumption markers prevent replay, re-init is fingerprint-idempotent, attestation TTL applies at re-init. No new failure mode.
• Security boundary: owner-only UDS + peer-credential UID pinning, never a network listener (TCP explicitly rejected); state-key provider executes in the sidecar's environment, removing host env as a secret channel. Attestation-bound channels are [DRAFT - decision-gated] feat(tbtc/signer): add TEE hardening checker stack #4007's scope.
• Conformance mechanism: the FFI contract tests become transport-parameterized; dlopen/sidecar divergence is a release blocker — that's what keeps "transport swap, not API rework" true over time.
• Sequencing: not on the 7.1–7.5 critical path (those build on dlopen); the sidecar track (7.S1–S3) runs parallel and must converge before ECDSA retirement per decision 1.

Open questions for sign-off (§8, proposed defaults)

(a) spawn model: keep-client child process; (b) framing: length-prefixed JSON; (c) connection model: pool with one in-flight request per connection; (d) packaging: same release artifact.

🤖 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 Plus

Run ID: db5d9a5f-7198-4af2-84d3-b5d5b0f69776

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 docs/phase-7-sidecar-addendum-2026-06-12

---

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.}