Fixing the Java-Python voice boundary with a gRPC contract

The Java API and Python voice engine are separate processes, so a protobuf contract makes change and failure more explicit than an untyped internal call. voice/v1/voice.proto defines synthesis, the voice catalog, and capabilities at one versioned boundary, while the Java client enforces a request deadline.

Contract essentials

• Synthesize accepts provider, text, voice, and request ID, and returns audio bytes, content type, duration, and provider.
• The Python server bounds text, request IDs, and message size. Provider bodies and input text are not copied into public errors.
• The Java blocking stub runs on a bounded elastic executor. When gRPC is disabled or fails, the existing REST TTS boundary is an explicit fallback.
• The public REST API remains. gRPC is an internal service contract, not a reason to force every API onto gRPC.

Completion criteria

1. Generated code in Java and Python uses the same proto source.
2. Deadline, provider, and disabled-server failures converge to safe error types and REST fallback.
3. When Spring MDC has a request ID, it is forwarded as protobuf request_id; it is correlation data, not a high-cardinality log key containing user input.
4. GetCapabilities and /health/capabilities reflect the actual server lifecycle.

Related course: Close gRPC and WebRTC boundaries with cost guards