// SPDX-FileCopyrightText: 2026 FocusFlow contributors
// SPDX-License-Identifier: AGPL-3.0-only

part of '../../reminder_policy.dart';

/// UI/platform-independent directive for one task reminder check.
class ReminderDirective {
  /// Creates a `ReminderDirective` instance with the values required by its invariants.
  /// Callers should pass already-normalized scheduler data because validation and defaulting belong at the model or service boundary, not in arbitrary UI code.
  const ReminderDirective({
    required this.taskId,
    required this.action,
    required this.reason,
    required this.effectiveProfile,
    required this.effectiveProfileSource,
    required this.evaluatedAt,
    this.scheduledStart,
    this.scheduledEnd,
    this.protectedFreeSlotTaskId,
    this.nextEligibleAt,
  });

  /// Task evaluated for reminder behavior.
  final String taskId;

  /// What an application layer may do.
  final ReminderDirectiveAction action;

  /// Stable reason code for tests, telemetry, and later UI copy.
  final ReminderDirectiveReason reason;

  /// Effective reminder profile used for the decision.
  final ReminderProfile effectiveProfile;

  /// Source of [effectiveProfile].
  final EffectiveReminderProfileSource effectiveProfileSource;

  /// Instant used to evaluate the directive.
  final DateTime evaluatedAt;

  /// Task scheduled start, when present.
  final DateTime? scheduledStart;

  /// Task scheduled end, when present.
  final DateTime? scheduledEnd;

  /// Active protected Free Slot that affected the decision, when any.
  final String? protectedFreeSlotTaskId;

  /// Next known time the application may re-check, when deterministic.
  final DateTime? nextEligibleAt;
}
