Configure Riverpod family provider and scoping
epic-speech-to-text-input-state-management-task-006 — Expose TranscriptionStateManager via a StateNotifierProvider.family keyed by fieldId string so that each dictation-enabled form field on screen maintains fully independent state. Register the provider in the app's ProviderScope with appropriate overrides for testing. Document the provider family pattern and ensure that disposing a field's provider properly cancels active SpeechRecognitionService subscriptions and persists any in-flight partial transcript before disposal.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
Use `final transcriptionProvider = StateNotifierProvider.autoDispose.family
Register `overrideWithValue` in ProviderScope for both SpeechRecognitionService and PartialTranscriptionRepository during widget and integration tests. Avoid placing the family declaration in the same file as TranscriptionStateManager to prevent circular imports — create a dedicated `transcription_providers.dart` in the component directory.
Testing Requirements
Unit tests (flutter_test + mocktail): (1) Verify two family instances with different fieldIds hold independent state after concurrent mutations. (2) Verify dispose triggers subscription cancellation on the mock SpeechRecognitionService. (3) Verify dispose calls PartialTranscriptionRepository.persist() with the correct in-flight transcript before stream is closed. (4) Verify ProviderScope.overrides correctly substitutes mock implementations for SpeechRecognitionService and PartialTranscriptionRepository.
Widget test: Mount a simple widget that watches two family providers simultaneously and confirm independent rebuild cycles. All tests must pass with zero Riverpod ProviderException warnings in output.
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.