[P2] ZARA-023 — Introduce an actor-style real-time turn coordinator with bounded mailboxes #24

New issue

Closed

opened 2026-07-18 19:23:05 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-07-18 19:23:05 +00:00

(Migrated from github.com)

Objective

Replace the monolithic wake-loop control flow with explicit concurrent stages suitable for streaming and cancellation.

Required design

Use an actor/message-passing model with bounded mailboxes and no shared mutable turn state across stages. Minimum logical actors/services:

AudioCapture — owns microphone stream and frame sequence.
Wake/VAD — emits wake, speech-start, speech-end, and partial utterance events.
TurnCoordinator — sole owner of conversation state, turn IDs, deadlines, cancellation, and acknowledgement policy.
Transcriber — accepts sequenced frames and emits partial/final text.
Router/Agent — Prolog-first routing and streamed model events.
SpeechOutput — owns TTS synthesis/playback and interruption.
Telemetry — consumes events without blocking the real-time path.

Required implementation

Define typed event schemas and actor lifecycle protocol: start, ready, message, cancel(turn), drain, stop, failed.
Enforce bounded queues and explicit overflow policy per actor.
Make cancellation idempotent and scoped by turn ID so stale results cannot speak in a newer turn.
Keep implementation minimal; use pykka
Preserve the repaired public CLI/config behavior.

Required tests

Deterministic actor tests for ordering, bounded mailboxes, stale-event rejection, actor failure/restart policy, shutdown, and cancellation races.
Add scripts/test-turn-coordinator.sh using fake actors.

Acceptance

The coordinator is the only writer of turn/conversation state.
Slow actors cannot grow memory without bound.
A cancelled turn cannot later emit notification or audio.

Branch

refactor/zara-023-realtime-actors

Dependencies

ZARA-020, ZARA-021, ZARA-022.

## Objective Replace the monolithic wake-loop control flow with explicit concurrent stages suitable for streaming and cancellation. ## Required design Use an actor/message-passing model with bounded mailboxes and no shared mutable turn state across stages. Minimum logical actors/services: - `AudioCapture` — owns microphone stream and frame sequence. - `Wake/VAD` — emits wake, speech-start, speech-end, and partial utterance events. - `TurnCoordinator` — sole owner of conversation state, turn IDs, deadlines, cancellation, and acknowledgement policy. - `Transcriber` — accepts sequenced frames and emits partial/final text. - `Router/Agent` — Prolog-first routing and streamed model events. - `SpeechOutput` — owns TTS synthesis/playback and interruption. - `Telemetry` — consumes events without blocking the real-time path. ## Required implementation - Define typed event schemas and actor lifecycle protocol: start, ready, message, cancel(turn), drain, stop, failed. - Enforce bounded queues and explicit overflow policy per actor. - Make cancellation idempotent and scoped by turn ID so stale results cannot speak in a newer turn. - Keep implementation minimal; use pykka - Preserve the repaired public CLI/config behavior. ## Required tests - Deterministic actor tests for ordering, bounded mailboxes, stale-event rejection, actor failure/restart policy, shutdown, and cancellation races. - Add `scripts/test-turn-coordinator.sh` using fake actors. ## Acceptance - The coordinator is the only writer of turn/conversation state. - Slow actors cannot grow memory without bound. - A cancelled turn cannot later emit notification or audio. ## Branch `refactor/zara-023-realtime-actors` ## Dependencies ZARA-020, ZARA-021, ZARA-022.

lost-rob0t commented

2026-07-19 05:33:17 +00:00

(Migrated from github.com)

Use Pykka and ZMQ