Define navigation route contract interfaces
epic-navigation-and-gesture-accessibility-service-and-audit-task-001 — Define the core Dart interfaces and data models that represent navigation route contracts: RouteAccessibilityContract, ModalRouteContract (requiring explicit close action), and BackNavigationContract (requiring back control for non-root routes). These interfaces form the foundation that both the service and the audit runner depend on.
Acceptance Criteria
Technical Requirements
Implementation Notes
Keep the interfaces as pure abstract classes rather than mixins — mixins complicate the audit runner's reflection-based validation. Use Dart's required keyword on all mandatory fields in ConcreteRouteConfig's constructor so missing fields are caught at compile time, not runtime. Define LiveRegionPolicy as a top-level enum in the same barrel file for discoverability. The distinction between ModalRouteContract and BackNavigationContract should be treated as composition (a modal route can also have back navigation), so design ConcreteRouteConfig to implement both simultaneously without ambiguity.
Consider adding a factory constructor ConcreteRouteConfig.tab() and ConcreteRouteConfig.modal() as named constructors to guide consumers toward correct usage patterns without requiring them to set every field manually.
Testing Requirements
Unit tests should verify the ConcreteRouteConfig reference implementation: (1) construction with valid arguments succeeds, (2) construction with an empty semanticsLabel triggers an AssertionError in debug mode, (3) a ModalRouteContract instance without an explicitCloseAction cannot be constructed (enforced by required parameter — verified by compile-time check), (4) a BackNavigationContract for a root route correctly represents the back action as a no-op via a documented sentinel value. Use flutter_test; no widget pump required. Test file: test/navigation/navigation_contracts_test.dart.
Flutter's SemanticsController used in integration tests is an internal or semi-internal API that can break between Flutter stable releases. If the audit runner relies heavily on undocumented semantics tree traversal, a Flutter upgrade could silently disable the audit checks without a build failure, creating false confidence.
Mitigation & Contingency
Mitigation: Use only the public flutter_test accessibility APIs (meetsGuideline, SemanticsController.ensureSemantics) and wrap all SemanticsController calls in a versioned helper class with explicit assertions that the expected semantics tree shape is still available. Pin the Flutter SDK range in pubspec.yaml.
Contingency: If SemanticsController APIs break on a Flutter upgrade, fall back to widget-level golden tests that include the semantics tree snapshot, combined with manual Switch Access and VoiceOver QA checklists executed before each release.
Flutter integration tests that simulate Switch Access traversal on multiple screens can be slow (30–120 seconds per test flow), which may make the audit runner impractical to run on every CI commit if the test suite already has long run times.
Mitigation & Contingency
Mitigation: Scope the audit runner to a dedicated integration test target that runs on pull requests targeting main and on nightly builds, not on every push. Parallelise test shards in CI to keep wall-clock time acceptable. Profile audit run times during development and trim any flows that duplicate coverage.
Contingency: If CI run times exceed acceptable thresholds, split the audit runner into a fast smoke suite (touch targets and semantic labels only, runs on every PR) and a thorough traversal suite (Switch Access simulation, runs nightly), with the nightly failure blocking the release branch rather than every PR.