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

part of '../../task_lifecycle.dart';

/// Immutable internal activity fact.
///
/// Activities are backend/application data, not a visible per-task history UI.
/// They carry enough stable structure for idempotency, statistics, and future
/// persistence adapters.
class TaskActivity {
  /// Creates a `TaskActivity` 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.
  TaskActivity({
    required String id,
    required String operationId,
    required this.code,
    required String taskId,
    required String projectId,
    required this.occurredAt,
    Map<String, Object?> metadata = const <String, Object?>{},
  })  : id = _requiredTrimmed(id, 'id'),
        operationId = _requiredTrimmed(operationId, 'operationId'),
        taskId = _requiredTrimmed(taskId, 'taskId'),
        projectId = _requiredTrimmed(projectId, 'projectId'),
        metadata = Map<String, Object?>.unmodifiable(metadata);

  /// Stable activity id supplied by the application boundary.
  final String id;

  /// Idempotency key for the user/application operation that created this fact.
  final String operationId;

  /// Stable activity category.
  final TaskActivityCode code;

  /// Task this activity belongs to.
  final String taskId;

  /// Project the task belonged to when the activity occurred.
  final String projectId;

  /// When the activity happened.
  final DateTime occurredAt;

  /// Small structured payload for later statistics and application use cases.
  final Map<String, Object?> metadata;
}
