---
title: "Turn budget"
description: "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."
type: "living"
source: "docs/contracts/turn-budget.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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.
