---
title: "Utterance records"
description: "One typed record of numbers per committed spoken utterance (utterance.v1): its timings, levels and prosody, the device key that keeps baselines apart, the ADR 0044 rules (off by default, never audio or words, computed after the commit), the Admin's per-day Utterances row and the fields later slices append."
type: "living"
source: "docs/contracts/utterance.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

utterance.v1 — one typed record per committed spoken utterance

- Status: **built, off by default** (`[utterance] rows`). The record, its switch and its Admin read. Nothing changes
  behavior on it yet. Adaptive endpointing (a shadow) shares its prosody estimator, not the record.
- The types: `UtteranceRecord` and its blocks, `AdminUtterances` and `AdminUtteranceDevice`, in
  `crates/protocol/src/utterance.rs`. ts-rs generates the TypeScript bindings into `packages/protocol`.
- The writer: `crates/voice_gateway/src/utterance.rs`.


## The rules (ADR 0044)

- **Off by default.** `[utterance] rows = false`. Off, a session allocates no ring, keeps no counter and writes no
  row, and the Admin row is absent. On, each session keeps a 12 s, 16 kHz mic ring in memory, overwritten, never
  stored.
- **Numbers only.** A record holds numbers, closed words and the channel's labels. It never holds audio or a word of
  the transcript. The first partial is held in memory until the commit, to say whether the commit kept it, then
  dropped. Nothing in the record is a diagnosis. Nothing in it changes behavior until the metric admission gate
  admits it.
- **Kept where it is heard.** The record is a row of the gateway's own session trace (`utterance`), on the gateway's
  host. It never goes into git, a receipt or a report. Receipts carry aggregates.
- **Per device, never mixed.** Every record names its device (`device.key`). Every baseline or aggregate is kept per
  key. A dedicated microphone on an audio interface is the reference channel for level and voice-quality numbers. A
  laptop's built-in mic is a room and context channel, because the OS AGC flattens its loudness.
- **Off the dispatch path.** At the commit the gateway reads the counters and the ring's sample index (microseconds).
  The blocking pool copies the utterance out of the ring, measures it and writes the row. Each record carries its own
  cost (`compute_us`).

## The record

One row per committed spoken utterance. A typed commit has no audio and gets no row. The trace row's event is
`utterance` and its data is the record:

| field | content |
|---|---|
| `schema` | `utterance.v1` |
| `turn_id` | the committed turn's id, to join the session's other rows |
| `committed_at_ms` | the commit, Unix ms |
| `device` | `key` (`<kind>:<source>`, the baseline key), `kind`, `role`, `source`, `room?`, `sample_rate_hz` |
| `timing` | see below |
| `text` | `chars`, `words`: the transcript's size, never its words |
| `level` | see below |
| `prosody` | see below |
| `compute_us` | the blocking task's cost, microseconds |

`timing`, from the recognizer's metrics rows:

| field | content |
|---|---|
| `segment_ms` | the last speech segment's length (`stt_speech_end`) |
| `segments` | speech segments closed since the previous commit |
| `endpoint_reason` | the endpoint's closed word (`hold_expired`, `no_hold`, `max_segment`, `flushed`, `held_chunk`) |
| `hold_ms` | the end-of-utterance hold in force |
| `decided_after_end_ms` | the speech end to the endpoint's decision (stream time) |
| `speech_end_to_commit_ms` | the speech end to the commit: the turn budget's `speech_end_to_commit` leg |
| `partials` | partial transcripts since the previous commit |
| `first_partial_kept` | whether the commit begins with the first partial's words; absent with no partial |
| `since_last_commit_ms` | the session's previous commit to this one; absent on the first |

`level`, over the utterance's 16 kHz audio (dB re full scale, 20 ms frames):

| field | content |
|---|---|
| `audio_ms` | the audio read: the segment, clipped to the ring |
| `peak_dbfs` | the loudest sample |
| `level_dbfs` | the median level of the active frames (within 35 dB of the loud ones) |
| `floor_dbfs` | the 10th-percentile level over the segment and the 250 ms before it |
| `snr_db` | `level_dbfs - floor_dbfs` |
| `clipped_share` | samples at or over 0.999 of full scale |

`prosody`, the live estimator's numbers: `speech_ms`, `voiced_share`, `reliable`, `chars_per_s`, `pause_mean_ms`,
`monoloudness_db`, `monotony_st`, `f0_spread_st`. The estimator is
`crates/voice_gateway/src/operator_affect/prosody.rs`, the same Rust YIN the operator-affect row uses, so one baseline
serves both. Nothing reads the f0 fields as behavior.

A new field is optional and appended at the end of its block, so a v1 reader keeps working.


## The Admin's Utterances row

`AdminPerformanceSnapshot.utterances`, in the Performance section's answer, holds:

- the UTC day and the day's record count;
- per device, at most eight (later keys count under `other`): the record count, and over its newest 500 records the
  medians of `speech_ms`, `speech_end_to_commit_ms`, the level, the signal-to-floor ratio (tenths of a dB) and the
  speaking rate (tenths of a character per second).

The row is absent while `[utterance] rows` is off. The socket's bound (`validate_performance_snapshot`) refuses a row
whose devices do not add up to its count. The fixture answer is in `benchmarks/fixtures/admin-sections.v1.json`.

## Rollback

Set `[utterance] rows = false` (the default) and restart: no ring, no row, no Admin row. An older Admin reads the
field as absent.
