Define OrganizationLabelsNotifier state model
epic-dynamic-terminology-and-labels-service-layer-task-001 — Create the Dart state classes and data models for OrganizationLabelsNotifier, including TerminologyMapState (loading, loaded, error), the TerminologyMap value type holding orgId + Map<String, String> + updatedAt timestamp, and the LabelsNotifierException hierarchy. These models form the contract consumed by all downstream providers.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use freezed if the team already has it as a dependency — it generates copyWith, ==, hashCode, and the sealed union pattern automatically with minimal boilerplate. If freezed is not used, implement the sealed class manually with Dart 3.0+ `sealed` keyword. The LabelsNotifierException hierarchy should mirror the TerminologyFailure types from the foundation layer (task-006) but is a distinct type — LabelsNotifierException is the service-layer contract, TerminologyFailure is the repository-layer contract. Map between them in the notifier implementation (a later task).
Define the initial state of OrganizationLabelsNotifier as TerminologyMapState.loading() so the UI always starts in a defined state. Document in the class-level comment that TerminologyMap.labels is a defensive copy (created with Map.unmodifiable()) to prevent downstream mutation.
Testing Requirements
Write a small unit test file verifying the state model contracts: (1) TerminologyMapState.loading is distinct from .loaded and .error in switch exhaustiveness; (2) TerminologyMap equality uses orgId + updatedAt (not label content); (3) TerminologyMap.copyWith(labels: newMap) produces a new instance with updated labels but same orgId; (4) all three LabelsNotifierException subtypes can be thrown and caught as Exception. These are simple structural tests — no mocks needed. Use flutter_test. Confirm that exhaustive switch on TerminologyMapState produces a compile error if a variant is missing (validated by attempting to compile a partial switch in a test helper).
When a user switches organization context (e.g., a coordinator with multi-org access), a race condition between the outgoing organization's map disposal and the incoming organization's fetch could briefly expose the wrong organization's terminology to the widget tree.
Mitigation & Contingency
Mitigation: Implement an explicit loading state in OrganizationLabelsNotifier that widgets check before rendering any resolved labels. The provider graph should cancel the previous organization's fetch via Riverpod's ref.onDispose before initiating the next.
Contingency: If the race manifests in production, fall back to English defaults during the transition window and emit a Sentry error event for investigation; the UX impact is a brief English flash rather than wrong-org terminology.
Supabase Row Level Security policies on organization_configs may inadvertently restrict the authenticated user from reading their own organization's labels JSONB column, causing silent empty maps that appear as English fallbacks.
Mitigation & Contingency
Mitigation: Write and test explicit RLS policies that grant SELECT on the labels column to any authenticated user whose organization_id matches. Add an integration test that verifies label fetch succeeds for each role (peer mentor, coordinator, admin).
Contingency: If RLS blocks are discovered in production, temporarily escalate label fetch to a service-role edge function while the RLS policy is corrected, ensuring no labels are exposed cross-organization.
A peer mentor who installs the app for the first time with no internet connection will have no cached terminology map and will see only English defaults, which may be confusing for organizations like NHF that use Norwegian-specific role names exclusively.
Mitigation & Contingency
Mitigation: Bundle a default fallback terminology map for each known organization as a compile-time asset (Dart asset file) so that even fresh installs without connectivity render correct organizational terminology immediately.
Contingency: If bundled assets are out of date, display a one-time informational banner noting that terminology will update on next connectivity restore, with no functional blocking of the app.