The ordinary Pi session owns execution; INTERACTIONS.md defines conversation and executor cooperation.
NativeVoiceCall coordinates the controller, speech adapter and Pi-owned widgets/history UI.
Use Pi theme, terminal-width and UI components; never take over raw input, the alternate screen or editor state.
Recognized speech never changes the editor.
The separately installed speak_to_me executable owns devices, microphone capture, playback, AEC, VAD, recognition, synthesis, models and native dependencies.
Voice owns conversation policy, endpoint selection, local turn identities, provisional captions, setup consent and call UX.
No agent roles, Voice turn IDs, cue-state names or Pi concepts cross the service boundary.
Production transport is JSON-RPC 2.0 over bounded NDJSON stdin/stdout; stderr is drained separately.
PCM stays inside the service.
The executable is launched directly without a shell; there is no Node IPC worker, native addon, inference dependency or automatic fallback.
service.info and asset planning inspect without activating devices or installing assets.
Setup approves the native plan's exact destinations, sizes, sources, checksums and licenses.
Only the service installs its assets; Voice never builds native code or changes system tools/settings.
The same inspected client is transferred to the call.
Prepared-client ownership covers cancellation and every failed handoff.
Call shutdown preserves certified playback accounting until the healthy close fence, then releases the controller and child.
Interaction and failure semantics
Provisional recognition is display-only; authoritative finals enter Voice's normal classification/submission path.
Voice acknowledges retained finals after consumption, never to request event replay.
Consumed-prefix notifications certify playback history; phrase captions, command acceptance and terminal events alone do not.
Frame durations use the resource's reported render rate.
Certification establishes neither physical audibility nor exact word timing.
Voice maps native process/resource/operation/segment IDs to local conversation identities.
Instance, epoch and call ownership fence stale events across mute, recovery, shutdown and session changes.
New work stops immediately during close; only final certified output accounting remains eligible until its close fence.
Queues, maps, framing, requests and shutdown deadlines are bounded.
Malformed responses, disconnected pipes and process death fail pending work instead of fabricating completion.
Mute cancels active native work and retained input through an epoch change.
Unmute waits for resource readiness, then starts a new recognition stream.
Barge-in interrupts Voice output, not unrelated Pi execution.
Native sound catalog digests select cues; local cue policy never becomes a native application state.
Speech synthesis and cue arbitration follow the service's operation lifecycle.
Recovery closes the old process, reinspects the same stable profile and requires its assets to remain ready.
It never installs assets, replays output or resubmits stale recognition.
Missing/changed profiles or new asset requirements require explicit setup.
Recovery is bounded and cannot survive hangup, reload or session replacement.
Native fixture processes must be treated as finite test runs, not silently switched to physical devices.
Distribution and verification
The root package distributes Voice's bundled JavaScript and metadata.
The native executable, native dependencies, models, device support and virtual-audio runner are separate.
No production module requires the checkout or a sibling extension.
The Node fake is an explicitly selected development/test executable and is not shipped as a production fallback.
The native project's JSON_RPC_SPEC.md and TEST_INTERFACE.md describe the proposed service contract.
Voice's implementation is transport, DTO validation, speech adapter, call coordination and widget.
Verification separates client integration evidence from native audio, physical-device and cross-platform acceptance.
# Native Voice architecture
## Runtime boundaries
The ordinary Pi session owns execution; [INTERACTIONS.md](INTERACTIONS.md) defines conversation and executor cooperation.
`NativeVoiceCall` coordinates the controller, speech adapter and Pi-owned widgets/history UI.
Use Pi theme, terminal-width and UI components; never take over raw input, the alternate screen or editor state.
Recognized speech never changes the editor.
The separately installed `speak_to_me` executable owns devices, microphone capture, playback, AEC, VAD, recognition, synthesis, models and native dependencies.
Voice owns conversation policy, endpoint selection, local turn identities, provisional captions, setup consent and call UX.
No agent roles, Voice turn IDs, cue-state names or Pi concepts cross the service boundary.
Production transport is JSON-RPC 2.0 over bounded NDJSON stdin/stdout; stderr is drained separately.
PCM stays inside the service.
The executable is launched directly without a shell; there is no Node IPC worker, native addon, inference dependency or automatic fallback.
`service.info` and asset planning inspect without activating devices or installing assets.
Setup approves the native plan's exact destinations, sizes, sources, checksums and licenses.
Only the service installs its assets; Voice never builds native code or changes system tools/settings.
The same inspected client is transferred to the call.
Prepared-client ownership covers cancellation and every failed handoff.
Call shutdown preserves certified playback accounting until the healthy close fence, then releases the controller and child.
## Interaction and failure semantics
Provisional recognition is display-only; authoritative finals enter Voice's normal classification/submission path.
Voice acknowledges retained finals after consumption, never to request event replay.
Consumed-prefix notifications certify playback history; phrase captions, command acceptance and terminal events alone do not.
Frame durations use the resource's reported render rate.
Certification establishes neither physical audibility nor exact word timing.
Voice maps native process/resource/operation/segment IDs to local conversation identities.
Instance, epoch and call ownership fence stale events across mute, recovery, shutdown and session changes.
New work stops immediately during close; only final certified output accounting remains eligible until its close fence.
Queues, maps, framing, requests and shutdown deadlines are bounded.
Malformed responses, disconnected pipes and process death fail pending work instead of fabricating completion.
Mute cancels active native work and retained input through an epoch change.
Unmute waits for resource readiness, then starts a new recognition stream.
Barge-in interrupts Voice output, not unrelated Pi execution.
Native sound catalog digests select cues; local cue policy never becomes a native application state.
Speech synthesis and cue arbitration follow the service's operation lifecycle.
Recovery closes the old process, reinspects the same stable profile and requires its assets to remain ready.
It never installs assets, replays output or resubmits stale recognition.
Missing/changed profiles or new asset requirements require explicit setup.
Recovery is bounded and cannot survive hangup, reload or session replacement.
Native fixture processes must be treated as finite test runs, not silently switched to physical devices.
## Distribution and verification
The root package distributes Voice's bundled JavaScript and metadata.
The native executable, native dependencies, models, device support and virtual-audio runner are separate.
No production module requires the checkout or a sibling extension.
The Node fake is an explicitly selected development/test executable and is not shipped as a production fallback.
The native project's `JSON_RPC_SPEC.md` and `TEST_INTERFACE.md` describe the proposed service contract.
Voice's implementation is [transport](src/speak-client.ts), [DTO validation](src/speak-protocol.ts), [speech adapter](src/speech-backend.ts), [call coordination](src/native-call.ts) and [widget](src/voice-widget.ts).
[Verification](TESTING.md) separates client integration evidence from native audio, physical-device and cross-platform acceptance.