# Streaming normalization architecture checklist

Use this with voice, platform, product, and QA owners before changing a streaming text-to-speech path.

## Canonical data

- [ ] Every structured value keeps a canonical machine-readable form.
- [ ] The spoken form is stored separately from the canonical value.
- [ ] A pronunciation rewrite cannot become a tool argument or business-system value.
- [ ] Entity provenance is recorded: caller audio, tool response, catalog, policy, or model inference.
- [ ] Locale and language are explicit when they change interpretation.

## Entity classes

Mark each class as `not used`, `raw TTS`, `deterministic rewrite`, `SSML`, `lexicon`, `model-assisted`, `clarify`, or `block`.

| Entity class | Strategy | Locale coverage | Owner | Evidence link |
| --- | --- | --- | --- | --- |
| Currency |  |  |  |  |
| Date |  |  |  |  |
| Time and timezone |  |  |  |  |
| Phone number |  |  |  |  |
| Long digit string |  |  |  |  |
| Email address |  |  |  |  |
| URL |  |  |  |  |
| Product or booking code |  |  |  |  |
| Measurement |  |  |  |  |
| Person and place name |  |  |  |  |
| Brand or medicine |  |  |  |  |
| Mixed-language text |  |  |  |  |

## Streaming boundary

- [ ] Stable text can stream without waiting for the entire sentence.
- [ ] Risky entities use a semantic holdback buffer.
- [ ] The buffer closes on an entity boundary, not a fixed character count alone.
- [ ] Currency symbols, URL prefixes, decimal points, slashes, and alphanumeric runs have explicit handling.
- [ ] The system never emits part of a sensitive value before its reading is resolved.
- [ ] The delivered text and audio chunk boundaries are logged for failed cases.
- [ ] Re-synthesis is measured and does not duplicate already-played audio.

## Ambiguity policy

- [ ] `03/04/26`-style dates resolve only from typed context or declared locale.
- [ ] Ambiguous account, product, or booking codes are spelled or clarified.
- [ ] High-risk unresolved values are blocked from speech.
- [ ] Clarification text does not guess the answer inside the question.
- [ ] The caller's correction supersedes every prior spoken form.

## Provider capability table

Complete this for every provider, engine, voice, and locale in production.

| Provider | Engine/model | Voice | Locale | `say-as` support | Phoneme support | Language switch support | Tested date |
| --- | --- | --- | --- | --- | --- | --- | --- |
|  |  |  |  |  |  |  |  |

- [ ] Unsupported SSML tags are rejected or removed safely.
- [ ] Reserved SSML characters are escaped.
- [ ] A model or voice upgrade reruns the pronunciation lock set.
- [ ] Provider fallback does not receive incompatible markup.

## Latency evidence

Capture p50, p95, and slow-call count for:

- [ ] First model token to first safe speech chunk.
- [ ] Entity buffer time by class.
- [ ] TTS request to first audio.
- [ ] First TTS audio to caller playback.
- [ ] Added normalization time.
- [ ] Re-synthesis count and duration.

## Audio tests

- [ ] Tests feed realistic token chunks, not only complete sentences.
- [ ] Tests save normalized text or SSML and rendered audio.
- [ ] Semantic correctness is a hard gate for amounts, dates, identifiers, and safety-sensitive terms.
- [ ] Reviewers can write critical values back from audio without seeing the text.
- [ ] Regional voices and code-switch points are covered.
- [ ] Allowed spoken variants and forbidden readings are documented.
- [ ] Canonical business values are compared before and after normalization.

## Release decision

- [ ] No critical semantic failure is open.
- [ ] No workflow depends on an undeclared locale guess.
- [ ] Tail latency stays inside the lane budget.
- [ ] Every failed class has an owner and safe fallback.
- [ ] Evidence is linked to the release record.