dyolink/docs/specs/voice-treatment-entry/spec.md

type, status, created, repos, aliases

type	status	created	repos	aliases
task	active	2026-08-20	repo path branch base role spec_slug merge_after dyolink ~/PersonalProjects/dyolink feat/treatment/add-voice-input-for-new-treatment-form origin/master extraction contract + resolvers + review sheet voice-treatment-entry	voice treatment entry voice input dictation mic

Voice treatment entry

Status: v1 is merged to master (c07f550…dc10d8d). The treatment form was then overhauled on top of it (a3c14a1, 7f92e73, 72f885d, 5d3597f): one prosthesis type per tooth became stacked jobs, jaw-level appliances and a category tree. Voice still compiles against that model but can no longer express it, and in two places now writes data the form itself refuses. This revision adapts the extraction contract (§5), the resolvers (§6) and the review sheet (§7), and carries two recording defects found on Safari (§2, §9). Still blocked on the ASR spike (§11 item 1) before it is trustworthy in front of patients Area: Treatment workspace (CLINIC orgs) Created: 2026-08-20 · Revised: 2026-09-07

Fill a TreatmentDetail — including its lab dispatch — by speaking, instead of by tapping through the type dropdown, the FDI chart, the prosthesis job popover and the lab picker.

---

1. Goal

A clinician on the Treatment tab taps a microphone, describes the treatment for the already-selected patient in one utterance, and is shown a review sheet of what was understood. Fields they tick are applied to the open detail chip. Nothing is written to the form without confirmation.

In scope

One recording produces exactly one TreatmentDetail, and may fill every field of it:

Field	Source
treatmentType	catalog code, matched against locale labels
teeth	FDI codes, via tooth-intent resolver
toothSelectionGroups	connected (bridge) / single spans
comment	cleaned dictated notes
lab: LabCaseToothProsthesis rows	one assignment list — a target is a tooth or a jaw, and carries a stack of job codes
lab: destinationOrganizationId	matched against the clinic's linked labs
lab: dueDate	via due-date intent resolver

Out of scope (v1)

• Multiple detail chips from one recording.
• attachmentIds — files cannot be dictated.
• Editing an existing detail by voice ("no, make that 15"). Confirming a recording always creates a new detail (see §2).
• Creating the treatment or selecting the patient by voice. A patient is already selected; voice only fills the form.
• Lab-side (LAB org) usage. Clinic only.

---

2. User flow and UI integration

The control: Add detail, split

The Add detail button gains a second segment holding the mic. The halves read as siblings — both end in a new detail — but they are independent actions:

• Add half — unchanged. Same onAddDetail, same seeding, same setEntryStep. It gains a neighbour and nothing else. Its logic is not modified, wrapped or made conditional.
• Mic half — starts a recording. Nothing is created until confirm (below).

The Add detail <Button> in TreatmentDetailsEditor becomes a segmented control built exactly like the detail chip's trash affordance in the same file (TreatmentDetailsEditor.tsx, the chip <div> + label <button> + remove <button>):

• an inline-flex items-stretch overflow-hidden rounded-[var(--radius-md)] wrapper;
• two raw <button> children divided by border-s, each with its own disabled, title, aria-label and focus-visible:ring-inset;
• styled primary (bg-primary text-white) to preserve the button's current look;
• w-full sm:w-auto on the wrapper with the Add half flex-1, reproducing today's fullWidth + sm:w-auto shrink-0 behaviour.

The shared Button component is not reusable for the halves: it hardcodes rounded-[var(--radius-md)] on each instance and owns auto-pending state, both of which fight a segmented control. This is precisely why the chip pattern uses raw <button>s, and this control follows it.

Side: the mic is the second flex child with border-s — the logical end, exactly like the trash. Visually right in en/nl, visually left in fa. No physical left/right anywhere, per the repo's RTL rule.

en / nl (LTR)          fa (RTL)
[  Add detail │ 🎤 ]   [ 🎤 │  افزودن  ]
[ ترمیم 14,15 │ 🗑 ]   [ 🗑 │ ترمیم 14,15 ]
        ↑ same side as the chip's trash, in both directions

Flow

[editable day]
        │
        ▼  tap 🎤        ← mic swaps to ■ (red); Add half disabled
   recording ─────────── inline bar below the header row:
        │                ● 0:12 / 2:00  ▁▃▇▅▂▆█▄▁   [لغو]
        │                auto-stops at the 2:00 cap
        ▼  tap ■
   processing ────────── ● transcribing…   ○ extracting     [cancel]
        │
        ▼
   review sheet
     ☑ Type        ترمیم
     ☑ Teeth       [mini FDI chart]  14 15
     ☑ Notes       حساسیت به سرما
     ☐ Lab         لابراتوار سینا      ⚠ similar name
        │
        ▼  [Apply n fields]
   detail created or filled → normal save flow

No layout shift. The segmented control never changes size; only the mic's icon and colour change. The timer and level meter live in a full-width bar inserted between the header row and the chip strip — the header is sm:justify-between, so growing the button mid-recording would shove the row on every start and every stop.

Duration is capped at 2 minutes (maxMs, configurable, v1 default 120_000). The timer shows elapsed / 2:00 and the recorder auto-stops at the cap. maxMs: null means uncapped and remains supported, but is not the v1 default.

Two minutes is generous against the longest realistic utterance — a full prosthesis dictation with type, several teeth, a bridge, prosthesis type, lab and due date — while bounding worst-case spend. It also sits comfortably inside the vendor limits (§4): 2 minutes of webm/opus is well under 1 MB against a 25 MB ceiling, and transcribes in a few seconds against a 60s processing timeout.

Cost per recording is therefore bounded at $0.012 of ASR (2 min × $0.006) plus ~$0.0008 of extraction — about 1.3¢ worst case, against ~0.3¢ for a typical 20s utterance.

What confirm does

The detail is created on confirm, never on tap. Tapping the mic starts a recording and nothing else, so cancelling, a vendor failure, a rate-limit, or navigating away leaves the chip strip untouched — there is no orphan state to clean up.

Confirm always appends a new detail. One unconditional rule, no dependence on invisible state: append newDetail() seeded with defaultTreatmentTypeForAppointment, make it active, setEntryStep('treatment'), then apply the ticked rows on top — so an extracted type overrides the seed, and unticking the type row leaves the seeded default in place.

This reuses newDetail() and the same state transitions, but it is a separate code path. onAddDetail is not called and not changed.

setEntryStep('treatment') matters: showChrome is always on, so the control is visible during the Lab wizard step too. Confirming there returns to the treatment step.

Confirm also saves. The new detail is persisted immediately (persistDraft({force:true})), and when the result carries a lab, a due date or a prosthesis map the lab case is saved with it (persistLabCases). Not politeness — the autosave effect watches details only, so a lab draft left in component state alone loses the destination lab, the due date and the whole prosthesis map on the next reload. The detail survives, which is what makes that loss look like a successful save.

One guard on it: persistDraft returns a preview treatment instead of saving when any detail still lacks a treatment type — the blank chip the workspace opens with is enough — and a preview's detail id falls back to the client id. Confirm therefore checks what came back, not the precondition, and skips the lab-case save when it did not get a real id; posting a lab case against an id the server has never seen fails the whole save. Checking the result rather than the condition keeps this true for every early return persistDraft has.

Accepted consequences:

• Tapping Add and then 🎤 leaves behind the blank chip that Add created. It carries the usual trash affordance.
• That same blank chip blocks confirm's immediate lab-case save until it is given a type or removed; the lab rows stay in local state until the ordinary Lab-step save.
• Dictating into an existing detail is not supported in v1 — voice always makes a new one.

Render policy

Three different reasons for "no", rendered differently:

Reason	Condition	Render
Technical	no voice profile for the locale; no MediaRecorder	segment absent — the control is byte-for-byte today's plain Add button
Commercial	Plan.features.voiceTreatmentEntry false	segment absent — ⚠ not enforced in v1, see §8
Contextual	!canEdit || disabled — past day, read-only load, no TAB_TREATMENT_EDIT	both segments render and disable together, like the chip's trash (disabled:opacity-40 disabled:cursor-not-allowed)

"This feature isn't yours" and "not right now" are different statements. Absence avoids a permanently dead control; disabling avoids the button resizing as the day strip moves.

The technical row was specified and never implemented. voiceForEditor gated the mic on the server's availability response alone — enabled && locales.includes(locale) — and never called isMediaRecorderSupported(). So the control rendered on a browser that cannot record and failed on tap, which is how the Safari report arrived. It now tests both. That is what "segment absent" meant all along.

TAB_TREATMENT_EDIT is resolved via common/membership-permissions.ts, never by reading membership.permissions directly.

Component API

TreatmentDetailsEditor gains exactly one optional prop. All behaviour — MediaRecorder, the API call, error state — lives in lib/voice/useVoiceCapture.ts (hooks belong in lib/ per AGENTS.md) and is owned by TreatmentWorkspace. The editor stays presentational and renders both the segment and the recording bar with its own classes, keeping the segmented styling beside the chip pattern it mirrors.

/** Omit when voice is unavailable — the Add button then renders unsplit. */
voice?: {
  phase: 'idle' | 'recording' | 'processing';
  elapsedMs: number;
  level: number;   // 0..1, for the meter
  maxMs: number | null;   // v1: 120_000 (2 min). null = uncapped, supported but not default
  onStart: () => void;
  onStop: () => void;
  onCancel: () => void;
};

voice === undefined is the absent state above — availability is expressed by presence rather than a separate flag, so the two cannot disagree.

Accessibility

• Mic segment carries both title and aria-label, like the chip's trash, and its label changes with phase.
• Announce phase transitions via a role="status" aria-live="polite" region — the same idiom as the existing autosave status line. Do not put aria-live on the ticking timer.
• Focus ring is focus-visible:ring-inset tinted primary when idle, red while recording.

---

3. Architecture

Two sequential stages, both server-side. The vendor API key never reaches the browser.

browser ──audio(base64)──► POST /treatments/voice-extract
                                    │
                          ┌─────────┴─────────┐
                          │ 1. AsrProvider    │  audio + locale hint → transcript
                          └─────────┬─────────┘
                          ┌─────────┴─────────┐
                          │ 2. ExtractionProv │  transcript + catalog + ctx → VoiceIntent
                          └─────────┬─────────┘
                          ┌─────────┴─────────┐
                          │ 3. resolvers      │  intents → FDI codes, ISO date
                          │    (pure, tested) │
                          └─────────┬─────────┘
                                    ▼
                          VoiceExtractionResult  (resolved values + the intents
                                                  that produced them, for display)

Why intents and not final values: the model never emits an FDI code and never does calendar arithmetic. It emits what it heard; deterministic, unit-tested code decides what that means. This is what makes the two highest-consequence mappings — quadrant mirroring and Jalali conversion — testable instead of hopeful.

Endpoint

POST /treatments/voice-extract

• Guards: JwtAuthGuard + ClinicOrgGuard.
• Service-level check of TAB_TREATMENT_EDIT. The plan flag is not checked in v1 (§8).
• Per-user throttle via @nestjs/throttler (present in package.json, currently wired nowhere in src/ — this is its first use, so the module must be registered in app.module.ts). Configurable; v1 default 6 requests / 60s per user (VOICE_THROTTLE_LIMIT, VOICE_THROTTLE_TTL). A human cannot approach that — a recording plus processing takes ten seconds at minimum — so it is purely an abuse and runaway-loop guard, which is doing more work than usual given v1 is ungated and uncapped (open item 14).
• Body: base64 audio + declared format + clientTodayIso + IANA timeZone + treatmentDetailId/clientId for context.

clientTodayIso and timeZone come from the client per the existing house rule (AGENTS.md): never derive the clinic's civil day from Date#getDay() on the UTC server. Reuse common/zoned-civil-time.ts.

---

4. Provider registry

ASR and extraction are separate swappable roles. They will not come from the same vendor for every locale.

interface AsrProvider {
  transcribe(audio: AudioInput, localeHint: string): Promise<{ text: string; usage: AsrUsage }>;
}

interface ExtractionProvider {
  extract(transcript: string, catalog: CatalogPrompt, ctx: ExtractionContext): Promise<VoiceIntent>;
}

Resolved through a registry keyed by locale.

At launch all three locales use the same profile — OpenRouter with openai/whisper-1 for ASR. The per-locale indirection is kept anyway, because the locale is the axis along which this is most likely to diverge: Persian ASR is the weakest link (§11), and swapping only fa to a Persian-specialist vendor must not be a code change.

VOICE_PROFILE_FA = openrouter:openai/whisper-1 | openrouter:<llm-model>
VOICE_PROFILE_EN = openrouter:openai/whisper-1 | openrouter:<llm-model>
VOICE_PROFILE_NL = openrouter:openai/whisper-1 | openrouter:<llm-model>

The language hint is the profile's locale as ISO-639-1 — fa, en, nl — not a constant.

Reachability is a property of where you deploy, not of the code. The same image serves an Iran-hosted instance with a domestic fa profile and a Europe-hosted instance with an OpenRouter profile; only config differs. A locale with no configured profile has no microphone button at all (§2).

The frontend must learn which locales are enabled from the API, not from a NEXT_PUBLIC_* var — those are baked in at build time, so an env-var approach would make enabling a locale require rebuilding and repushing the frontend image.

v1 provider: OpenRouter

Both roles, one API key.

ASR — POST https://openrouter.ai/api/v1/audio/transcriptions

{
  "model": "openai/whisper-1",
  "input_audio": { "data": "<base64>", "format": "webm" },
  "language": "fa"
}

• Accepted formats: WAV, MP3, FLAC, M4A, OGG, WebM, AAC. Chrome/Android webm/opus and Safari/iPad mp4/aac both go through unmodified — no transcode dependency is required.
• Limits: 25 MB; 60s upstream processing timeout. The 2-minute recording cap (§2) sits comfortably inside both.
• Request shape verified against OpenRouter's STT docs: base64 JSON input_audio is the documented primary path (multipart file is the OpenAI-compatible alternative), and both default model slugs exist on the live models API.
• The cap is enforced twice: the client's reported durationMs, and again against the vendor's own usage.seconds — the client's figure is a claim, not enforcement. The server allows a 2s tolerance, because the client measures length after the recorder stops and a recording that runs to the cap always reports slightly over it.
• Response: { text, usage: { seconds, total_tokens, cost } }.
• Price: openai/whisper-1 is $0.006/minute, billed to the nearest second → $0.002 for a typical 20s utterance, $0.012 at the 2-minute cap. OpenRouter forwards this model directly to OpenAI.

Extraction — OpenRouter chat completions with a JSON schema constraining the output to VoiceIntent. Model id is config (VOICE_LLM_MODEL).

Chosen: google/gemini-3.7-flash.

Cost is deliberately not the selection axis. The call is ~1,250 input tokens (system prompt + catalog labels + JSON schema + linked labs + transcript) and ~200 output, so the whole candidate field spans about one cent per recording:

Model	in / out per M tokens	≈ per call
google/gemini-3.7-flash	$0.375 / $1.875	$0.0008
qwen/qwen3.8-27b	$0.45 / $3.20	$0.0012
qwen/qwen3.8-max	$2 / $6	$0.0037
openai/gpt-5.6-terra	$2 / $12	$0.0049
anthropic/claude-opus-5	$5 / $25	$0.0113

Select for Persian comprehension and reliable constrained JSON instead. Gemini Flash wins on the reasoning that this task is not reasoning-heavy — read a short sentence, pick codes from a supplied closed list, emit small JSON — and it is simultaneously the cheapest and lowest-latency candidate, which matters on a pipeline already at 3–10s.

Escalation path if Persian comprehension proves weak on real transcripts (item 1): qwen/qwen3.8-max (leads current multilingual rankings, ~4.6× the cost) and then anthropic/claude-opus-5 as the accuracy ceiling. Both are a config change — VOICE_LLM_MODEL — not a code change. Worth knowing when judging that ranking evidence: it is marked provisional and was measured on the previous Qwen generation.

---

5. Extraction contract

The model returns intents only. Illustrative shape:

type VoiceIntent = {
  treatmentType: string | null;          // catalog code, from the supplied closed list
  teeth: ToothIntent[];
  connectedSpans: { from: ToothIntent; to: ToothIntent }[];
  comment: string | null;
  prosthesis: ProsthesisAssignment[];    // empty array, never null
  labId: string | null;                  // must be one of the supplied linked-lab ids
  labMatchExact: boolean;
  due: DueIntent | null;
};

/** One spoken instruction: these targets get these jobs. */
type ProsthesisAssignment = {
  targets: ToothIntent[];   // each one a tooth, or a jaw — see below
  types: string[];          // leaf codes, or one category / subcategory code
  spoken: string;           // the transcript span, echoed back to the clinician
};

type ToothIntent =
  | { kind: 'explicit'; fdi: string; spoken: string }
  | { kind: 'positional'; arch: 'upper' | 'lower' | 'both';
      side: 'patient_right' | 'patient_left'; position: number; spoken: string };

type DueIntent =
  | { kind: 'weekday'; weekday: string; which: 'this' | 'next' }
  | { kind: 'offset'; unit: 'day' | 'week' | 'month'; amount: number }
  | { kind: 'jalali'; jy: number; jm: number; jd: number }
  | { kind: 'gregorian'; y: number; m: number; d: number };

The wire form stays deliberately flat (extraction.wire.ts): strict json_schema mode has poor support for discriminated unions, so every variant field is present and nullable and toVoiceIntent narrows it.

One assignment list, no default

prosthesisDefaultType and prosthesisOverrides are gone. A default that fills every tooth and is then overwritten per tooth has a precedence rule, and a precedence rule has a wrong side — the first live prosthesis test previewed PFZ on tooth 13 and filled PFM. A single list where every entry names its own targets has no precedence to get wrong.

Targets are ToothIntents; the examples below write them as bare FDI codes for brevity.

• { targets: [12, 13], types: ['pfm_crown'] } — two teeth, one job. Everything the default expressed, without the default.
• { targets: [12], types: ['zirconia_abutment', 'monolithic_zirconia'] } — one tooth, a stack. This is what the old shape could not say at all.

A target is a tooth or a jaw, and the code decides which

Nothing on the wire declares "this is a jaw". A target that names an arch and no position is a jaw, and the resolver confirms that against the chartRegion of the assignment's codes. arch gains 'both', which the old enum could not express.

Deriving it costs no second source of truth. The catalog already answers the question, and partial_denture — a removable code that is nonetheless assigned per tooth — already ships with chartRegion: 'crown' in catalog-seed-data.ts, so the exception needs no special case either.

A code whose region contradicts its target is reported, never coerced. An arch appliance aimed at tooth 12, or a crown aimed at the upper jaw, resolves to code_not_valid_for_target (§6).

types[] may hold a leaf or a category

"روکش" is crown — a category with nine leaves, not a material. The model returns the category code it actually heard rather than guessing pfm_crown, and the review sheet offers the leaves as chips (§7).

This needs no extra field because the namespaces are disjoint: 42 leaf codes against 7 category names and 4 subcategory names, no collisions. The resolver classifies by lookup. A test asserts the disjointness, because a future catalog entry named crown would quietly turn a leaf into an ambiguity.

Prosthesis work implies the treatment type

prosthesis is the only labDependent treatment type. Any resolved assignment therefore forces treatmentType to prosthesis, and the sheet locks that row while the prosthesis row is ticked. Without it, a recording that names an appliance but no treatment type seeds the type from the appointment purpose, prosthesisAssignActive stays false, the plain chart renders, and the lab rows are orphaned behind a chart that cannot show them.

Closed lists

Every code-valued field is constrained to a closed list supplied in the prompt:

• Treatment types and prosthesis types come from CatalogLabelService in the actor's locale, so the model sees "پروتز" and "زیرکونیا مونولیتیک" as the spoken forms of prosthesis and monolithic_zirconia rather than being asked to translate. Catalog entities store a stable code and no label — never hardcode a label.
• The prosthesis list is no longer flat. buildCatalog already receives category, subcategory, chartRegion and stackGroup from ProsthesisCatalogService and throws all four away. It now passes them through, so the prompt presents the catalog as the tree it is and marks which codes are jaw-level. Still no catalog knowledge hardcoded in the prompt — the shape comes from the data.
• Lab candidates are the clinic's linked labs only (OrganizationLink), passed as { id, name }. The model may return one of those ids or null, nothing else.

Every unresolved or rejected item is reported, never silently dropped.

---

6. Resolvers

Both live in backend/src/, pure and Jest-covered. That placement was originally forced — the frontend had no test runner at all. This revision adds Vitest for the frontend's pure helpers (§12), so the split is now a judgement rather than a constraint: intent resolution stays on the backend because it is the trust boundary, and the stack rules stay on the frontend because that is where the form's own rules already live.

resolveToothIntent()

• Owns the patient-right convention in exactly one place: upper + patient_right → quadrant 1, upper + patient_left → 2, lower + patient_left → 3, lower + patient_right → 4. This is the mirroring bug, and it becomes a unit test.
• Rejects out-of-range positions rather than clamping. Position 9 is unresolved, never 8.
• Permanent dentition only — FDI 11–18/21–28/31–38/41–48, matching FDI_UPPER_LEFT_TO_RIGHT / FDI_LOWER_LEFT_TO_RIGHT. Deciduous references ("دندان شیری") must resolve to unresolved, never snap to a permanent tooth.
• Locale-neutral by construction. ToothIntent carries arch/side/position, not words, so the resolver needs no per-locale branches. The locale-specific part is the prompt: each enabled locale needs its own spoken tooth vocabulary (شش بالا راست, upper right six, rechtsboven zes).
• A spoken tooth number is an FDI code, in every locale. This is how clinicians actually dictate — "بیست و شش" is tooth 26 — so the prompt teaches the notation (first digit = quadrant from the patient's own point of view, second = position from the midline) rather than refusing it. arch/side/position is the reading of a tooth that was described instead of numbered, where a single digit is a position and the quadrant comes from words. Revised after the first live test; the original design had this backwards and made the descriptive form the only supported path.
• A single digit alone is never resolved. "دندون دو" names four teeth. It is reported as tooth_missing_quadrant with the candidate codes attached — narrowed by whatever was said, so "دو بالا" offers two — and the review sheet turns them into chips. The clinician chooses; the resolver still never guesses.
• Digits arrive in three scripts. normalizeFdiCode (common/fdi.ts) folds Persian and Arabic-Indic digits to ASCII and strips the spaces of a digit-by-digit dictation before anything is matched, at both the wire branch choice and the final validation.

resolveDueDate()

• Takes clientTodayIso + IANA timeZone; reuses common/zoned-civil-time.ts.
• Week start is per locale, because "next Thursday" is week-relative: fa starts Saturday, en and nl start Monday. Hardcoding Saturday put an en/nl clinician's deadline a week out. One place (weekStartForLocale), tested in both directions.
• 'this' is occurrence-anchored (soonest strictly-future, never resolves into the past); 'next' is week-anchored. A missing qualifier is read as 'this' — a bare weekday carries none, and failing would discard a real spoken deadline.
• Jalali conversion is arithmetic, not inference: port jalaliToGregorian and toLatinDigits from frontend/src/lib/i18n/persianCalendar.ts into backend/src/common/jalali.ts with a spec. It is dependency-free integer math (~60 relevant lines) and the calendar does not change, so the duplication is stable.

Group / prosthesis rules

• Connected spans validate through the shipped helpers — areArchNeighbors, sameArch, teethBetweenInclusive. Never a 1-tooth connected group. Anything invalid degrades to singles and is flagged on the review sheet. Spans stay their own array rather than folding into assignments: linking is offered on the plain chart too (the non-prosthesis onToggleLink branch in TreatmentWorkspace.tsx), so it is not prosthesis-only.
• An assignment target is a selection. On a prosthesis detail a tooth exists only by carrying a job: applyCodes in ProsthesisAssignChart returns early on an empty code list, and pruneDetailTeethToJobs strips the rest before every save. So tooth_not_selected is unreachable for prosthesis work and is retired.
• A tooth with no job is named and left out. "۱۲ و ۱۳، روکش برای ۱۲" adds only 12; 13 appears struck through in the sheet reading no prosthesis heard. Keeping it would manufacture a state the manual chart cannot produce and persistDraft would delete on the way out.
• Stack legality is not a resolver concern. canStackLeaf, categoryDisabledForJobs and the screw-retained exclusion live in frontend/src/components/treatment/prosthesisTree.ts, and the backend's own dispatch check knows nothing about stacking. Porting them would make the voice path stricter than the manual path and create two copies of a rule that must never disagree. The sheet and the apply path both route through applyLeafToJobs instead (§7). The backend checks only that a code exists and that its region suits its target.
• All-or-nothing is retired. assertCompleteToothProsthesisMap still requires every remaining tooth on a prosthesis detail to carry a code, but the new form guarantees that by pruning rather than by refusing, and it now also accepts a detail with no teeth and an arch job. So an incomplete map no longer blocks a tick; the field survives only to name the targets that will be dropped.
• Apply order is teeth → groups → prosthesis, so pruneToothProsthesisForGroups behaves.

Unresolved reasons

Every one is rendered with what was heard, so the clinician sees what the system did not understand. Three of them carry candidates and become chips (§7).

Reason	Meaning	Carries
not_permanent_tooth	deciduous, or outside the permanent set	—
position_out_of_range	a position outside 1–8	—
tooth_missing_quadrant	a lone digit — four teeth match, fewer when an arch or side was also heard	candidates: FDI codes
prosthesis_type_ambiguous	a category or subcategory was heard, not a material	candidates: leaf codes
arch_not_spoken	a jaw-level appliance with no jaw	candidates: upper, lower
code_not_valid_for_target	an arch code aimed at a tooth, or a tooth code aimed at a jaw	—
unknown_catalog_code	a code the supplied catalog does not contain	—
span_not_same_arch	a connected span crossing arches	—
malformed	neither an FDI code nor a usable description	—
invalid_date	a date the resolver cannot build	—

tooth_not_selected is removed — assignments now define their own teeth.

---

7. Review sheet

Presentation: a modal on desktop; a full-screen overlay on mobile.

⚠ On mobile this must be an overlay rendered in place — not a Next.js route. A real navigation unmounts TreatmentWorkspace and destroys the in-progress draft. This is the same constraint the realtime soft-refresh already lives under: never remount the treatment form, never clear a draft.

• Renders the transcript, then one row per extracted field in the app's own vocabulary: translated catalog labels, and a mini FDI chart for the teeth rather than a list of numbers.
• Each row has a checkbox. Ticked rows apply; nothing else is touched. Confirm is also what creates the new detail — see §2.
• Rows default to ticked except the lab row when labMatchExact is false — shipping to a lab always requires a deliberate tick.

Teeth and prosthesis are one row

For a lab-dependent type they are not independent, and two checkboxes let the clinician save a state the form immediately undoes. On master today, ticking teeth and unticking prosthesis on a prosthesis detail saves an empty detail: persistDraft prunes lab-dependent details to their jobs and applyVoiceResult persists straight after applying.

So a lab-dependent type gets one Teeth and prosthesis row that applies together. Every other type keeps a plain teeth row and has no prosthesis row at all. The merged row is:

• the existing read-only mini FdiToothChart, now fed crownColors / rootColors from toothRegionColors and archHighlight from the arch jobs. The chart already accepts all three, so showing stacks and jaw work costs no new component;
• a line underneath naming each target and what lands on it — ۱۲: ایمپلنت + روکش زیرکونیا · ۱۳: روکش پی‌اف‌ام · فک بالا: نایت گارد.

The chart catches a misheard tooth number at a glance; the list confirms the material. Either one alone is the weaker check.

The sheet previews the stack that will actually land

The merged row builds its preview through applyLeafToJobs — the same function the manual chart writes through — and applyVoiceResult applies through it too. A job the stack rules refuse, such as an implant plus a post & core on one tooth, is shown struck through and named. Not silently dropped, and not silently applied. The rules stay in one file (§6).

Three chip kinds, one pattern

An item carrying candidates renders them as tappable chips — the one place the sheet is interactive. Picking one folds the choice into the result, so an under-specified item is one tap from resolved instead of a dead end. Everything the sheet renders comes from that folded result, not the raw one.

Heard	Missing	Chips
"دندون دو"	the quadrant	the four FDI candidates, narrowed by any arch or side also heard
"روکش"	the material	the leaves of that category or subcategory
"نایت گارد"	the jaw	Upper / Lower, multi-pick — picking both is how a both-jaw appliance is expressed, since the manual chart has no both control either

Nothing is guessed on the clinician's behalf. A per-category default material would have the same shape as the auto-fill this design already rejects.

The sheet is a contract

Confirm fills exactly what the sheet previewed — no more. Any per-detail convenience that would top the case up afterwards has to be suppressed for a voice-created case, because a default that quietly adds a prosthesis type to a tooth the sheet never mentioned turns the confirmation step into a lie about what it was going to do — which is the whole reason the step exists.

The v1 branch carried an exemption for one such default, the dispatch panel's remembered-prosthesis auto-fill. master deleted that feature outright (f52ad6b), so the exemption went with it and nothing enforces this rule in code today. It is a constraint on whatever gets added next, not a description of something that exists.

This is also why a missing material becomes chips rather than a per-category default, and why a jobless tooth is named rather than quietly filled.

RTL

Logical text-start / text-end only, never text-left / text-right. Dates via lib/i18n/format.ts. The merged row's per-target line reads right to left in fa, so the separator is a bare · with no direction of its own.

---

8. Gating and configuration

Gate = TAB_TREATMENT_EDIT ∧ canEditTreatmentForDay ∧ configured locale profile ∧ Plan.features.voiceTreatmentEntry. How each failing condition renders is in §2.

Plan.features is a Json column that already exists on the Plan model and is seeded as {} for all five plans — and is read nowhere in backend/src/. Voice is its first consumer, so:

• No migration is needed.
• The read should go through a small generic helper, since this establishes the pattern for every future flag.
• Voice is metered vendor spend, which is why the gate is commercial (plan) rather than a new TAB_* permission — a clinician who can already edit the form gains no capability from voice, only speed.

The per-user throttle is a separate, non-commercial abuse control.

v1 ships ungated

The plan flag is designed but not enforced in v1 — voice is open to every clinic user who can edit treatments, in every configured locale. Plan.features.voiceTreatmentEntry and the availability API stay documented here as the intended gate, deferred rather than dropped, so turning them on later is additive.

Consequence to accept deliberately: with no plan gate, the per-user throttle and the 2-minute recording cap are the only controls on metered vendor spend. See open item 14.

---

9. Errors

Per the three-layer contract: a code in common/errors/error-codes.ts, the throw site, and an errors.X key in all three of frontend/messages/{en,fa,nl}.json. Never a raw English Nest exception for a user-facing failure.

Code	When
VOICE_MIC_DENIED	microphone permission actually refused, or no input device — client-side only: needs the errors.X key in all three message files, but no ErrorCode entry and no throw site. Reserved for a real permission failure: see the note below
VOICE_CLIP_TOO_LONG	over maxMs (server-side re-check), over vendor limits, or a request body past the DTO's size cap
VOICE_UNSUPPORTED_FORMAT	the browser cannot record at all — no MediaRecorder, no container both it and the API accept, or a recorder that throws after permission was granted; and server-side, a format outside VOICE_AUDIO_FORMATS
VOICE_ASR_FAILED	transcription stage failed
VOICE_EXTRACT_FAILED	transcript obtained, structuring failed
VOICE_NOTHING_RECOGNIZED	empty or unusable transcript
VOICE_NOT_AVAILABLE	no profile for locale (v1); plan flag off, once enforced
VOICE_RATE_LIMITED	throttle

Two of these are raised by DTO validation, not by a throw site. validationExceptionFactory returns a constraint's message verbatim when the message is itself a known ErrorCode, so the voice DTO names its own failures: @MaxLength(…, { message: ErrorCode.VOICE_CLIP_TOO_LONG }) and @IsIn(…, { message: ErrorCode.VOICE_UNSUPPORTED_FORMAT }). Left to the shared constraint map they fall through to VALIDATION_FIELD_REQUIRED and VALIDATION_LANGUAGE_INVALID — an oversized recording telling the clinician a field is missing, and an unsupported container telling them their language is invalid. Any new voice constraint should name its code the same way.

VOICE_MIC_DENIED is only for a real permission failure. Three client paths used to report it for something else entirely — no MediaRecorder, no acceptable container, and a recorder that throws after permission was already granted. All three are "this browser cannot record" and now report VOICE_UNSUPPORTED_FORMAT; blaming the microphone sends the clinician hunting in site settings for a permission nothing ever asked for.

The container list is a preference, not a requirement. pickRecordingMimeType returned null when MediaRecorder.isTypeSupported rejected all six candidates — five of which are WebM or OGG, which Safari cannot record. So Safari was refused outright, even though it records audio/mp4, mimeTypeToFormat already maps that to m4a, and the backend accepts m4a. It now falls back to the empty hint, which is the let the browser choose path the function already had for Safari versions that shipped no isTypeSupported; onstop derives the real container from recorder.mimeType, as it already did. VOICE_UNSUPPORTED_FORMAT is left for a browser that genuinely cannot record.

Transcript salvage — specified, NOT built. The backend half exists: VOICE_EXTRACT_FAILED carries details.transcript and HttpExceptionFilter forwards it. The client half was never written — onError only resolves a message through getUserFacingError, which never reads details, so the transcript is shipped in an error body and dropped. Either build the dialog below or stop returning the transcript; shipping dictation to the client and discarding it is the worst of both.

When ASR succeeded and only extraction failed, the response still carries the transcript and the failure dialog offers "افزودن به یادداشت". That action creates a new detail with only comment set to the transcript — everything else left at newDetail() defaults. The words were captured and paid for; only the structure was lost.

This keeps the feature's one invariant intact: voice never writes into an existing detail. Dictating into an already-filled detail is a separate, later feature with its own voice-to-text control scoped to that field (§1, out of scope).

It also does not bypass the confirmation rule — the dialog shows the transcript, and the dentist taps to accept it. That review matters, because a raw transcript carries ASR errors and may contain the patient's spoken name, and comment is persisted (§10).

---

10. Data handling

• Audio is held in memory for the request only. Never written to disk, never a Prisma row. Note this is deliberately unlike treatment attachments, which do persist to backend/uploads/treatments.
• The transcript goes to the browser for the review sheet and dies with it.
• The comment field persists a cleaned version of what was said — that is legitimate clinical record-keeping and is the only durable trace.
• Telemetry is structured and patient-free: clip duration, which fields resolved, unresolved count, vendor latency, usage.cost, outcome (applied / discarded / failed), locale. Never the transcript, never audio, never a patient identifier. The destination is an open question — this repo has no metrics infrastructure yet (open item 9). Emit it as structured log lines in the interim so the fields exist and can be routed later without changing call sites.

Cancelling aborts the in-flight vendor call via AbortController, rather than letting it settle and discarding the result. Note this reduces spend but does not eliminate it: work already performed upstream may still be billed.

Recordings are clinical descriptions of identifiable patients leaving the server for a third party. Confirm the provider's retention and training policy in writing before enabling this for real clinics.

---

11. Open items

1. Persian ASR accuracy on tooth numbers is unmeasured, and it decides the feature. Everything downstream assumes a usable transcript; no design choice above compensates for a bad one. Run this before writing feature code.

   Why tooth numbers specifically, not general accuracy: a transcript can score well on WER and still be useless here, because the errors land on the digits. چهار (4) / چهارده (14) / چهل (40) differ by one syllable. FDI spoken as یک چهار may return as ۱۴, 14, or یک چهار. Persian and Latin digit scripts mix within one transcript. Jargon is loanwords (زیرکونیا, پرسلن فیوزد تو متال, اینله/آنله) and clinicians code-switch into English mid-sentence. Suction and handpiece run in the background.

   Protocol: ~25 utterances from a dentist reading a script covering explicit FDI, quadrant-relative phrasing, bridges, prosthesis types, due dates and notes — recorded on the real device, ideally once quiet and once with the operatory running. POST each to /api/v1/audio/transcriptions with language: "fa". Score per-tooth-reference accuracy (of every tooth spoken, how many survive recoverably?) and jargon recognition separately. Notes accuracy barely matters. ~6 minutes of audio ≈ $0.04.

   Decision it drives: if tooth accuracy holds, build. If not, the fix is not prompt tuning — it is pointing the fa ASR slot at a Persian-specialist vendor while en/nl keep whisper-1. That is a config change precisely because of decision 23.

   Unverified lead for that fallback: recent Persian-ASR benchmark work reports Qwen3-Omni as the strongest open Persian ASR. Not confirmed as available on OpenRouter's transcription endpoint — check before relying on it.

   Byproduct: the recordings become the fixture corpus for item 2.

2. VOICE_LLM_MODEL — resolved: google/gemini-3.7-flash (§4). Still worth validating on real whisper output during item 1, since clean transcripts flatter every model; the escalation path if Persian comprehension disappoints is documented in §4 and is a config change.

3. Production reachability — resolved: confirmed reachable from the Iranian production host. The per-locale registry is retained regardless (decision 23), so the fa profile can still be repointed at a domestic vendor if item 1 goes badly.

4. Provider retention/training policy — resolved: restricted via OpenRouter's account-level privacy/data-policy settings. Note this is an account setting, not a per-request one: re-verify it if the API key or the OpenRouter account changes, and remember whisper-1 is forwarded to OpenAI, so the effective policy is OpenRouter's plus that provider's.

5. English tooth numbering — resolved: a bare two-digit number is read as FDI in all three locales. FDI is what the product is built on and what clinicians dictate. Known trade-off, accepted: a clinician trained under Universal numbering says "tooth 14" and means a different tooth, so an en clinic needs either training or a later per-org notation setting. Revisit if a US clinic is onboarded.

6. nl and en have no spike data. The Persian spike (item 1) should be repeated per locale before that locale's mic is enabled for real users — same protocol, same scoring, different speaker.

7. Transcript salvage has no target — resolved: salvage creates a new detail with only comment set to the transcript (§9). Preserves the invariant that voice never writes into an existing detail; dictating into a filled detail becomes a separate later feature with its own field-scoped control.

8. Throttle limits — resolved: configurable, v1 default 6 requests / 60s per user (§3). Unreachable by a human; a pure abuse guard.

9. Telemetry has no sink. §10 defines exactly what to record but not where it goes — this repo has no metrics or analytics infrastructure yet. Deliberately deferred until it does. Interim: structured log lines, so the fields exist and can be routed later without touching call sites.

10. Review sheet modality — resolved: modal on desktop, full-screen overlay on mobile (§7). Not a route — navigating would unmount TreatmentWorkspace and destroy the draft.

11. Cancel and in-flight requests — resolved: abort via AbortController to limit spend (§10). Upstream work already performed may still be billed.

12. Recording duration cap — resolved: 2 minutes, configurable via maxMs (§2). Still worth timing a realistic worst-case prosthesis dictation during item 1 to confirm 2 minutes is comfortable rather than tight.

13. Availability API — resolved for v1: voice ships open to everyone with a configured locale profile. No plan check, no availability endpoint. The Plan.features design in §8 is deferred, not dropped.

New

14. Cost exposure is bounded but ungated in v1. With the 2-minute cap (12) and the 6/60s throttle (8), worst case is 12 audio-minutes per user-minute ≈ $0.072/min, or ~$4.30 per hour of sustained abuse by one user — bounded, not free. Normal use is far below this: a clinician doing 60 recordings a day at ~20s each costs about $0.18/day.

    What remains open is that there is no per-organization limit at all, because v1 ships ungated (13). Worth deciding what to watch and at what number to react. Mitigations, already designed and each a config or flag change: enforce the Plan.features gate, lower maxMs or the throttle, or add an org-level monthly minute budget.

15. The voice body limit is raised before any guard runs. isVoiceExtractPath in common/body-parsers.ts selects the large JSON limit by path, and Express body parsers run ahead of JwtAuthGuard. So an unauthenticated request to that path may upload the full clip-sized body before anything rejects it. The throttle does not help: it is a guard too. Bounded by the DTO cap and by the reverse proxy's own limit, but it is a pre-authentication allocation and nobody has decided whether that is acceptable. Not changed in this revision.

16. Transcript salvage is still specified and not built. VOICE_EXTRACT_FAILED carries details.transcript, HttpExceptionFilter forwards it, and nothing on the client reads it — getUserFacingError resolves a message only. The field also does not match ApiError['details'], which is an array. Either build the dialog in §9 or stop returning the transcript. Carried forward unchanged; it is orthogonal to the prosthesis model.

---

12. Verification

Machine gates

• cd backend && npm test — the existing suites, plus new coverage for the revised contract:
  • an assignment resolves its targets, and a target that names an arch with no position resolves to the UA / LA sentinels;
  • a leaf code, a category code and a subcategory code are each classified correctly, and the three namespaces are asserted disjoint;
  • an arch code aimed at a tooth, and a tooth code aimed at a jaw, both resolve to code_not_valid_for_target;
  • a resolved assignment forces treatmentType to prosthesis;
  • a target with no types is reported and excluded, and does not fail the whole assignment. The pre-existing suites stay: resolveToothIntent in all four quadrants, out-of-range rejection, deciduous → unresolved, resolveDueDate per-locale week start, "this" vs "next", Jalali leap year and month-end, and connected-span validation.
• cd backend && npm run build — cross-cutting backend gate.
• cd frontend && npx vitest run — new. One dev dependency, one config, one script, covering the pure helpers only: prosthesisTree.ts (stack legality, applyLeafToJobs precedence, toothRegionColors) and voiceReviewRows.ts (row availability, the merged row, folding chips into the result). No React, no DOM. CLAUDE.md is updated in the same commit — "there are no frontend tests" stops being true.
• cd frontend && npx tsc --noEmit — frontend type gate.
• cd frontend && npm run build — production build.
• ESLint on every touched file, no new warnings.

Manual

fa locale, editable day, prosthesis detail with a bridge, dispatch to a linked lab. Then:

Carried forward, still required

• past day → both segments disabled, control still split (not absent);
• locale with no profile → control renders unsplit, identical to today;
• fa vs en → mic sits at the logical end in both, on the same side as the chip's trash;
• cancel mid-recording → chip strip unchanged, no orphan detail;
• confirm → always appends a new chip, whatever the active detail contains;
• Add half → behaves exactly as it did before this change;
• no layout shift in the header row on record start, stop, or the 2:00 auto-stop;
• hold past 2:00 → auto-stops and proceeds to processing, not an error;
• cancel during processing → the vendor request is actually aborted;
• review sheet on mobile → full-screen overlay; closing it leaves the draft intact;
• confirm with a lab, a due date or a prosthesis map, then reload → all three are still there.

New to this revision

• Safari on macOS, and Safari on iPad → the mic records, and the clip reaches the server as m4a. This is the report that started the revision;
• a browser with no MediaRecorder → the Add button renders unsplit, and no mic appears;
• stack — "دندون ۱۲ ایمپلنت با روکش زیرکونیا" → the sheet shows both jobs on 12, the chart colours crown and root differently, and the chart after apply shows the same stack;
• jaw appliance — "نایت گارد فک بالا" → the sheet shows an upper-jaw row, the treatment type row reads prosthesis and is locked, and apply produces a UA row with no teeth;
• jaw not spoken — "نایت گارد" → Upper / Lower chips; tapping both produces UA and LA;
• material not spoken — "دندون ۱۲ روکش" → chips for the nine crown leaves; nothing is applied until one is picked;
• tooth with no job — "۱۲ و ۱۳، روکش پی‌اف‌ام برای ۱۲" → 13 is struck through in the sheet, apply adds only 12, and 13 is not silently saved and then deleted;
• illegal stack — "دندون ۱۲ ایمپلنت و پست و کور" → the refused job is struck through and named; apply writes only the legal one, and the manual chart agrees;
• contradiction — "دندون ۱۲ نایت گارد" → reported as code_not_valid_for_target, nothing applied for that assignment;
• two different materials — "۱۲ روکش پی‌اف‌ام، ۱۳ روکش پی‌اف‌زد" → the form shows both. Nothing may rewrite a per-tooth type the sheet already showed;
• non-lab-dependent type — "ترمیم برای دندون ۱۴" → a plain teeth row, no prosthesis row, and the teeth survive the save.

---

13. Decision log

Settled in a grilling session on 2026-08-20.

#	Question	Decision
1	Scope	Everything including lab dispatch
2	AI supply chain	Domestic provider originally; OpenRouter for v1, registry keeps both open
3	Apply model	Review sheet, then apply
4	Speech → FDI	LLM emits intent, code resolves. A spoken number is the FDI code (revised 2026-08-21, §6)
5	Cardinality	One detail per recording
6	Lab destination	Closed list of linked labs, explicit confirm, unticked when inexact
7	Due date	Intent + deterministic resolver
8	Resolver location	Backend, Jalali math ported
9	Prosthesis	Default type + overrides, all-or-nothing
10	Retention	Discard audio and transcript, non-PHI telemetry only
11	Capture	Tap to start/stop, hard cap (see 27)
12	Failure UX	Stage-aware codes, transcript salvage
13	Locales	Provider registry per locale; all three locales enabled
14	Reachability	Registry now, slots filled per deployment
23	ASR model	openai/whisper-1 for every locale; registry kept so fa can diverge
24	Extraction model	google/gemini-3.7-flash; escalation path documented in §4
25	Salvage target	Creates a new detail with only comment set — voice never writes into an existing detail
26	Throttle	Configurable; v1 default 6 requests / 60s per user
27	Duration cap	2 minutes, configurable via maxMs
28	Review sheet	Modal on desktop, full-screen overlay (not a route) on mobile; candidate chips are its only interactive part
29	Cancel	Aborts the in-flight vendor call
30	v1 gating	Open to everyone; Plan.features gate deferred, not dropped

Added while getting the first live recordings working (2026-08-21):

#	Question	Decision
31	Tooth numbering	A spoken number is its FDI code, in all three locales. A lone digit stays unresolved and offers its candidate teeth as chips (§6, §7)
32	What confirm writes	Confirm persists the detail and its lab case, because autosave watches details only — but skips the lab-case save when it got a preview treatment back (§2)
33	Preview as contract	Applying a voice result fills exactly what the sheet showed. Per-detail conveniences that would add more are suppressed for that case (§7)
15	Gating	Plan.features flag — its first consumer

UI placement settled in a second grilling session on 2026-08-20.

#	Question	Decision
16	Mic action	Independent record action; the Add half's logic is untouched
17	Record UI	Mic segment toggles ▶/■; inline bar below the header row
18	Unavailable	Absent for technical + commercial; disabled for contextual
19	Component API	One optional voice object prop; undefined means absent
20	Side	Logical end (border-s), exactly like the chip's trash
21	Creation	On confirm, never on tap
22	Creation rule	Confirm always appends a new detail — no blank-reuse guard

Adapting to the overhauled treatment form, in a grilling session on 2026-09-07.

#	Question	Decision
34	Scope	Full parity — voice reaches stacked jobs, jaw-level appliances and the category tree
35	Intent shape	One prosthesis assignment list. prosthesisDefaultType + prosthesisOverrides are removed, and with them the precedence rule that mis-filled tooth 13 (§5)
36	Arch targets	Derived, not declared — an arch with no position, confirmed against the code's chartRegion. arch gains 'both' (§5)
37	Partial codes	types[] may hold a category or subcategory code; the namespaces are disjoint and a test asserts it (§5)
38	Stack legality	Frontend only, in prosthesisTree.ts. Both the sheet and the apply path route through applyLeafToJobs; the backend never learns the rules (§6)
39	Sheet rows	Teeth and prosthesis merge into one row for lab-dependent types — they are not independent, and two ticks could save an empty detail (§7)
40	Tooth with no job	Named and left out. The manual chart cannot produce a jobless tooth, so voice must not either (§6)
41	Type coupling	A resolved assignment forces treatmentType to prosthesis and locks that row (§5)
42	Missing material	Chips for the category's leaves. Never a per-category default — that is the auto-fill shape this design rejects (§7)
43	Missing jaw	Upper / Lower chips, multi-pick. Picking both is how a both-jaw appliance is expressed (§7)
44	Frontend tests	Vitest added for the pure helpers. The split between backend and frontend resolvers becomes a judgement rather than a constraint (§6, §12)
45	Recording defects	Carried in this branch: the container fallback that refused Safari, and the render gate that never checked isMediaRecorderSupported() (§2, §9)
46	Delivery	One merge request