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

part of '../../../../application_layer.dart';

/// Repository contract for exactly-once operation records.
abstract interface class ApplicationOperationRepository {
  /// Runs the `findById` operation and completes after its asynchronous work finishes.
  /// Callers should await the returned future so repository writes, UI refreshes, and failure handling happen in a predictable order.
  Future<ApplicationOperationRecord?> findById(String operationId);

  /// Runs the `findByIdempotencyKey` operation and completes after its asynchronous work finishes.
  /// Callers should await the returned future so repository writes, UI refreshes, and failure handling happen in a predictable order.
  Future<ApplicationOperationRecord?> findByIdempotencyKey({
    required String ownerId,
    required String operationId,
  });

  /// Runs the `save` operation and completes after its asynchronous work finishes.
  /// Callers should await the returned future so repository writes, UI refreshes, and failure handling happen in a predictable order.
  Future<void> save(ApplicationOperationRecord operation);

  /// Runs the `insertIfAbsent` operation and completes after its asynchronous work finishes.
  /// Callers should await the returned future so repository writes, UI refreshes, and failure handling happen in a predictable order.
  Future<RepositoryMutationResult> insertIfAbsent(
    ApplicationOperationRecord operation,
  );
}
