Turn budget
Each turn leg's millisecond budget (speech end to commit, commit to first text, first text to first audio, first audio to audible, a tool round, a panel's paint, a barge's stop): the p50/p90 table, how a budget is set from a read, the rule that a change adding ms to a leg names the leg that gives them back, and where the Admin's Turn budget row and the offline reader show it.
Living doc, checked against the code 2026-11-14
turn-budget.v1 — each turn leg’s millisecond budget
- Status: live. A feature that adds 50 ms to a turn names the 50 ms it saves elsewhere.
- The table:
docs/contracts/turn-budget.v1.toml. The gateway compiles it in (crates/voice_gateway/src/turn_budget.rs), so the Admin row and the contract cannot drift.tools/telemetry/turn_budget.pyreads the same file over traces.
The legs
A spoken turn is cut into legs that end where the next begins. Each leg has a closed name: the table’s leg, which
is also the Admin’s wire word. No wire word carries token, which the Admin socket blanks.
| leg | from | to | traced by |
|---|---|---|---|
speech_end_to_commit |
the segmenter’s speech end (stt_endpoint_decided minus decided_after_end_ms) |
turn_user_committed |
both rows |
commit_to_first_text |
the commit | the brain’s first text (brain_first_token) |
both rows; the turn.brain_first_token span and its legs |
first_text_to_first_audio |
the first text | the TTS worker’s first audio chunk (tts_first_audio_chunk) |
both rows; the turn.tts_* spans |
first_audio_to_audible |
the first chunk | the client’s first frontend_audio_play_observed {active} |
both rows; turn.frontend_playback_start |
tool_round |
a round’s first tool call opening | its last result | tool_round {ms, calls} |
visual_paint |
a render sent to the frontend | its drawn receipt |
render_receipt.paint_ms |
barge_stop |
an interrupt’s arrival (the client’s barge-in, else the interrupt frame) | the gateway’s AudioReset |
barge_stop {ms, reason} |
Reach legs ([[reach_legs]])
A remote turn over vulpine/voice/1 (ADR 0053’s voice addendum)
has two legs that the reach edges measure, not the gateway. They sit in the table’s own [[reach_legs]] list,
outside the gateway’s compiled leg list, the Admin’s row and the gate’s legs.
| leg | from | to | traced by | budget (design) |
|---|---|---|---|---|
reach_uplink |
the client’s capture | the helper’s PCM out to the gateway | not yet: it needs a clock-offset estimate between the two edges | p50 80 / p90 150 ms |
reach_jitter |
a reply’s first frame arrival | its first slot due | voice_media first_depth_ms (the client relay) |
p50 60 / p90 120 ms |
reach_jitter is part of first_audio_to_audible. It is reported, never added a second time. Reach is off the
in-house turn path.
The four turn legs sum to VART (speech end to audible, tools/telemetry/felt_latency.py). Wake to the speech end is
the operator speaking and is not a budget. A tool round and a paint sit inside or beside the brain’s leg. They get
their own budgets because a new tool or panel is where a feature adds time. The rows carry milliseconds, counts and
closed words only: never a word, a turn id or a tool’s name.
The budget
Each leg has a p50_ms and a p90_ms budget and a basis:
measured: the newest real read’s nearest-rank p50/p90, rounded up to the next 50 ms. The read needs at least 30 samples of the leg. The table keeps it undermeasuredbeside the budget.design: the leg had fewer than 30 samples. The budget is a design bound until a read has 30.
A leg is over when its p50 or its p90 is above the budget.
The rules
- A change on the turn path states its cost in milliseconds per leg, with a trace receipt (a
turn_budget.pyread before and after, or a bench that isolates the leg). - A change that adds X ms to a leg names the leg that gives X ms back, in the same item. A leg under budget has slack to spend, and spending it is still stated.
- A budget moves only in the commit that carries the receipt measuring it, and only down, unless the operator rules otherwise on a named trade.
- A new leg (a new seam on the turn path) gets a row, a trace row or span, and a
designbudget in the same change.
The gate
The merge enforces rules 1 and 2: a change to a turn-path file carries a TURN-BUDGET: block that states each
touched leg’s measured delta, its receipt, and the leg that gives the time back
(python3 tools/repo/turn_budget_gate.py template prints it).
Where it shows
- The Admin’s Performance section, Turn budget: each leg’s p50/p90 over its newest
window_turnssamples against the budget, over-budget legs first and marked (AdminPerformanceSnapshot.turn_budget,AdminTurnBudget). The samples live in the gateway’s Performance store and start empty at every gateway start. - Offline:
python3 tools/telemetry/turn_budget.py <trace.jsonl>... [--json]over a copy of the gateway’s traces prints the same table with each leg’s sample count. On traces without thetool_round,render_receipt.paint_msandbarge_stoprows, it pairs the presence, render and barge rows instead.