/// Pure-Dart route-pop policy for SDD-028 (`BackIntentService`).
///
/// Trace: SDD-028 §2 (deterministic route-pop ordering) / SAD-018.
///
/// This file intentionally has **no Flutter dependency** so it can be
/// unit-tested without a `MaterialApp` or `Navigator` context. The
/// integration wrapper lives in `back_intent_service.dart`.
library;

/// Decision produced by [decideBackIntent].
///
/// Trace: SDD-028 §2 — exactly one decision per platform back event.
sealed class BackIntentDecision {
  const BackIntentDecision();
}

/// PTT is currently transmitting; the back event must be swallowed
/// without any UI side effect (SDD-028 §2.a).
class IgnoreDueToPtt extends BackIntentDecision {
  const IgnoreDueToPtt();
}

/// A modal / dialog route is on top; close it only (SDD-028 §2.b).
class CloseModal extends BackIntentDecision {
  const CloseModal();
}

/// Navigator can pop a non-root route (SDD-028 §2.c).
class PopRoute extends BackIntentDecision {
  const PopRoute();
}

/// At the root route with no modal and no PTT; the platform shall be
/// asked to finish the activity (SDD-028 §2.d — `exitCandidate`).
class ExitApp extends BackIntentDecision {
  const ExitApp();
}

/// Resolve the back-intent decision deterministically.
///
/// Trace: SDD-028 §2. The branch order is intentionally fixed:
///
///   1. `pttActive == true`       → [IgnoreDueToPtt]
///   2. `modalOpen == true`       → [CloseModal]
///   3. `atRoot == false`         → [PopRoute]
///   4. otherwise                 → [ExitApp]
///
/// This function is pure: identical inputs always produce identical
/// outputs and there are no side effects, which is the verification
/// surface targeted by SWE4-UV-042.
BackIntentDecision decideBackIntent({
  required bool pttActive,
  required bool modalOpen,
  required bool atRoot,
}) {
  if (pttActive) {
    return const IgnoreDueToPtt();
  }
  if (modalOpen) {
    return const CloseModal();
  }
  if (!atRoot) {
    return const PopRoute();
  }
  return const ExitApp();
}
