Define DictationState sealed class hierarchy
epic-speech-to-text-input-state-management-task-001 — Define the sealed class / freezed union representing all dictation states: DictationIdle, DictationRequestingPermission, DictationRecording, DictationProcessing, DictationComplete, and DictationError. Each state should carry the relevant payload (e.g., DictationComplete holds final transcript text, DictationError holds an error code and message). Use Dart sealed classes with Freezed for exhaustive pattern matching across the UI and service layers.
Acceptance Criteria
Technical Requirements
Implementation Notes
Place the file at lib/features/dictation/models/dictation_state.dart. Follow the project's existing Freezed pattern — check whether the project uses @Freezed() or @freezed and match. Use Dart 3 sealed class syntax (sealed class DictationState with _$DictationState) combined with Freezed's union factory pattern. Run dart run build_runner build --delete-conflicting-outputs after generating.
If the project uses a custom lint ruleset, ensure the generated file is excluded via analysis_options.yaml exclude pattern. The DictationErrorCode enum should be defined in the same file or a co-located error_codes.dart — do not scatter it across unrelated files. Avoid making DictationState extend any Flutter framework class; it is a pure domain model.
Testing Requirements
Unit tests only. Write one test file (dictation_state_test.dart) with the following cases: (1) assert DictationIdle == DictationIdle() value equality; (2) assert DictationComplete('hello') != DictationComplete('world'); (3) assert exhaustive switch compiles and routes each subtype to the correct branch; (4) assert DictationError.copyWith can update the message field; (5) assert DictationErrorCode contains all required enum values. Minimum coverage: all six state classes and DictationErrorCode exercised. All tests must pass with flutter test.
If a peer mentor rapidly switches between dictation-enabled fields while a session is still processing, the Riverpod family provider may share state or the SpeechRecognitionService may receive conflicting start/stop commands, causing orphaned recording sessions or state corruption.
Mitigation & Contingency
Mitigation: Design the state manager to enforce a single active dictation session globally via a shared active-field-key notifier. When a new field requests dictation while another session is active, automatically issue a stop command to the existing session and await completion before starting the new one. Test this concurrency scenario explicitly.
Contingency: If concurrency issues persist in integration testing, add a global dictation mutex at the SpeechRecognitionService level that serialises all start requests, with a short debounce to handle rapid field switching.
The recovery flow for interrupted dictation sessions (app restart with persisted partials) has ambiguous UX requirements. If recovery is automatic and the user has already typed different content into the field, the merge logic may overwrite or duplicate user input, causing data loss.
Mitigation & Contingency
Mitigation: Define the recovery behaviour explicitly: recovery should surface as an opt-in prompt ('You have unsaved dictation — insert or discard?') rather than an automatic merge. The state manager emits a dedicated recoverable-partial state that the UI layer renders as a non-blocking action sheet.
Contingency: If the recovery UI adds too much complexity for the initial release, scope recovery to display only the partial text in the preview field on re-open without auto-insertion, letting the user manually copy if needed, and defer the automatic recovery prompt to a subsequent iteration.