Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.py reads 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 under measured beside 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

  1. A change on the turn path states its cost in milliseconds per leg, with a trace receipt (a turn_budget.py read before and after, or a bench that isolates the leg).
  2. 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.
  3. 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.
  4. A new leg (a new seam on the turn path) gets a row, a trace row or span, and a design budget 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_turns samples 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 the tool_round, render_receipt.paint_ms and barge_stop rows, it pairs the presence, render and barge rows instead.

Was this page helpful?