<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for field integrity checking and repair.
 *
 * Detects and repairs orphaned field definitions in the
 * entity.definitions.installed key-value store that can cause
 * EntityStorageException when deleting media entities.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface FieldIntegrityServiceInterface {

  /**
   * Checks field integrity for module-created fields.
   *
   * Compares entity.definitions.installed entries with actual
   * FieldStorageConfig entities to detect inconsistencies.
   *
   * @return array<int, array{type: string, entity_type: string, field_name: string, details: string}>
   *   List of detected problems. Each entry has:
   *   - type: 'orphaned_definition', 'missing_definition', or
   *     'pending_deletion'
   *   - entity_type: The entity type ID
   *   - field_name: The field machine name
   *   - details: Human-readable description of the problem
   */
  #[\NoDiscard]
  public function check(): array;

  /**
   * Repairs detected field integrity problems.
   *
   * @param array<int, array{type: string, entity_type: string, field_name: string, details: string}> $problems
   *   Problems as returned by check(). If empty, runs check() first.
   *
   * @return array{repaired: int, failed: int, details: array<int, string>}
   *   Repair results with counts and per-item detail messages.
   */
  #[\NoDiscard]
  public function repair(array $problems = []): array;

  /**
   * Gets the timestamp of the last integrity check.
   *
   * @return int|null
   *   Unix timestamp or NULL if never checked.
   */
  #[\NoDiscard]
  public function getLastCheckTime(): ?int;

}
