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

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

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

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

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

  /// Return owner-scoped projects, optionally including archived profiles.
  Future<RepositoryPage<ProjectProfile>> findByOwner({
    required String ownerId,
    bool includeArchived = false,
    RepositoryPageRequest page = const RepositoryPageRequest(),
  });

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

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

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

  /// Archive a project without deleting task history.
  Future<RepositoryMutationResult> archive({
    required String projectId,
    required String ownerId,
    required int expectedRevision,
    required DateTime archivedAt,
  });
}
