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

part of '../../repositories.dart';

/// Repository contract for task documents.
abstract interface class TaskRepository {
  /// Return a task by stable id, or null when it does not exist.
  Future<Task?> findById(String id);

  /// Return a task plus owner/revision metadata.
  Future<RepositoryRecord<Task>?> findRecordById(String id);

  /// Return all tasks currently known to the repository.
  Future<List<Task>> findAll();

  /// Return tasks with a lifecycle status.
  Future<List<Task>> findByStatus(TaskStatus status);

  /// Return owner-scoped tasks in deterministic id order.
  Future<RepositoryPage<Task>> findByOwner({
    required String ownerId,
    RepositoryPageRequest page = const RepositoryPageRequest(),
  });

  /// Return tasks assigned to [projectId].
  Future<RepositoryPage<Task>> findByProjectId({
    required String ownerId,
    required String projectId,
    RepositoryPageRequest page = const RepositoryPageRequest(),
  });

  /// Return direct children owned by [parentTaskId].
  Future<RepositoryPage<Task>> findByParentTaskId({
    required String ownerId,
    required String parentTaskId,
    RepositoryPageRequest page = const RepositoryPageRequest(),
  });

  /// Return backlog candidates ordered by backlog age, then id.
  Future<RepositoryPage<Task>> findBacklogCandidates(
    BacklogCandidateQuery query,
  );

  /// Return tasks that overlap [window] by scheduled start/end.
  Future<List<Task>> findScheduledInWindow(SchedulingWindow window);

  /// Return owner-scoped scheduled tasks that overlap [window].
  Future<RepositoryPage<Task>> findScheduledInWindowForOwner({
    required String ownerId,
    required SchedulingWindow window,
    RepositoryPageRequest page = const RepositoryPageRequest(),
  });

  /// Return tasks in a local-day window. Civil date is supplied for adapters
  /// that store date-derived keys; in-memory filtering uses [window].
  Future<RepositoryPage<Task>> findForLocalDay({
    required String ownerId,
    required CivilDate localDate,
    required SchedulingWindow window,
    RepositoryPageRequest page = const RepositoryPageRequest(),
  });

  /// Save or replace [task] by stable id.
  Future<void> save(Task task);

  /// Save or replace every task by stable id.
  Future<void> saveAll(Iterable<Task> tasks);

  /// Insert [task] if its id is unused.
  Future<RepositoryMutationResult> insert({
    required Task task,
    required String ownerId,
  });

  /// Compare-and-set save by expected repository revision.
  Future<RepositoryMutationResult> saveIfRevision({
    required Task task,
    required String ownerId,
    required int expectedRevision,
  });

  /// Delete [taskId] by expected repository revision.
  Future<RepositoryMutationResult> deleteIfRevision({
    required String taskId,
    required String ownerId,
    required int expectedRevision,
  });
}
