<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Entity;

use Drupal\Core\Entity\ContentEntityInterface;
use Drupal\Core\Entity\EntityChangedInterface;
use Drupal\Core\Entity\EntityStorageInterface;
use Drupal\flowdrop_orchestration\DTO\Snapshot\WorkflowSnapshot;
use Drupal\user\EntityOwnerInterface;

/**
 * Interface for the FlowDrop Workflow Snapshot entity.
 *
 * This entity provides persistent storage for workflow execution snapshots,
 * enabling workflow resume, handover between orchestrators, and state
 * inspection capabilities.
 *
 * @internal
 *   This class is not part of the public API and may change without notice.
 */
interface FlowDropWorkflowSnapshotInterface extends ContentEntityInterface, EntityChangedInterface, EntityOwnerInterface {

  /**
   * Gets the workflow ID this snapshot belongs to.
   *
   * @return string
   *   The workflow ID.
   */
  public function getWorkflowId(): string;

  /**
   * Sets the workflow ID.
   *
   * @param string $workflow_id
   *   The workflow ID.
   *
   * @return static
   *   The entity instance.
   */
  public function setWorkflowId(string $workflow_id): static;

  /**
   * Gets the workflow version hash.
   *
   * @return string
   *   The workflow version hash.
   */
  public function getWorkflowVersion(): string;

  /**
   * Sets the workflow version hash.
   *
   * @param string $version
   *   The workflow version hash.
   *
   * @return static
   *   The entity instance.
   */
  public function setWorkflowVersion(string $version): static;

  /**
   * Gets the snapshot status.
   *
   * @return string
   *   The status (pending, running, completed, failed, paused,
   *   approval_required).
   */
  public function getSnapshotStatus(): string;

  /**
   * Sets the snapshot status.
   *
   * @param string $status
   *   The status.
   *
   * @return static
   *   The entity instance.
   */
  public function setSnapshotStatus(string $status): static;

  /**
   * Gets the node states as a serialized array.
   *
   * @return array<string, array<string, mixed>>
   *   The node states keyed by node ID.
   */
  public function getNodeStates(): array;

  /**
   * Sets the node states.
   *
   * @param array<string, array<string, mixed>> $node_states
   *   The node states keyed by node ID.
   *
   * @return static
   *   The entity instance.
   */
  public function setNodeStates(array $node_states): static;

  /**
   * Gets the initial input data.
   *
   * @return array<string, mixed>
   *   The initial input data.
   */
  public function getInitialInput(): array;

  /**
   * Sets the initial input data.
   *
   * @param array<string, mixed> $initial_input
   *   The initial input data.
   *
   * @return static
   *   The entity instance.
   */
  public function setInitialInput(array $initial_input): static;

  /**
   * Gets the snapshot metadata.
   *
   * @return array<string, mixed>
   *   The metadata.
   */
  public function getSnapshotMetadata(): array;

  /**
   * Sets the snapshot metadata.
   *
   * @param array<string, mixed> $metadata
   *   The metadata.
   *
   * @return static
   *   The entity instance.
   */
  public function setSnapshotMetadata(array $metadata): static;

  /**
   * Gets the StateGraph-specific messages.
   *
   * @return array<array<string, mixed>>
   *   The messages array.
   */
  public function getMessages(): array;

  /**
   * Sets the StateGraph-specific messages.
   *
   * @param array<array<string, mixed>> $messages
   *   The messages array.
   *
   * @return static
   *   The entity instance.
   */
  public function setMessages(array $messages): static;

  /**
   * Gets the StateGraph-specific data.
   *
   * @return array<string, mixed>
   *   The data array.
   */
  public function getData(): array;

  /**
   * Sets the StateGraph-specific data.
   *
   * @param array<string, mixed> $data
   *   The data array.
   *
   * @return static
   *   The entity instance.
   */
  public function setData(array $data): static;

  /**
   * Gets the iterator state for array processing.
   *
   * @return array<string, mixed>|null
   *   The iterator state or NULL.
   */
  public function getIteratorState(): ?array;

  /**
   * Sets the iterator state.
   *
   * @param array<string, mixed>|null $iterator_state
   *   The iterator state.
   *
   * @return static
   *   The entity instance.
   */
  public function setIteratorState(?array $iterator_state): static;

  /**
   * Gets the current node ID being executed.
   *
   * @return string
   *   The current node ID.
   */
  public function getCurrentNodeId(): string;

  /**
   * Sets the current node ID.
   *
   * @param string $node_id
   *   The node ID.
   *
   * @return static
   *   The entity instance.
   */
  public function setCurrentNodeId(string $node_id): static;

  /**
   * Gets the iteration count.
   *
   * @return int
   *   The iteration count.
   */
  public function getIterationCount(): int;

  /**
   * Sets the iteration count.
   *
   * @param int $count
   *   The iteration count.
   *
   * @return static
   *   The entity instance.
   */
  public function setIterationCount(int $count): static;

  /**
   * Gets the error message if execution failed.
   *
   * @return string|null
   *   The error message or NULL.
   */
  public function getError(): ?string;

  /**
   * Sets the error message.
   *
   * @param string|null $error
   *   The error message.
   *
   * @return static
   *   The entity instance.
   */
  public function setError(?string $error): static;

  /**
   * Gets the thread ID for conversation continuity.
   *
   * @return string|null
   *   The thread ID or NULL.
   */
  public function getThreadId(): ?string;

  /**
   * Sets the thread ID.
   *
   * @param string|null $thread_id
   *   The thread ID.
   *
   * @return static
   *   The entity instance.
   */
  public function setThreadId(?string $thread_id): static;

  /**
   * Gets the execution ID that created this snapshot.
   *
   * @return string|null
   *   The execution ID or NULL.
   */
  public function getExecutionId(): ?string;

  /**
   * Sets the execution ID.
   *
   * @param string|null $execution_id
   *   The execution ID.
   *
   * @return static
   *   The entity instance.
   */
  public function setExecutionId(?string $execution_id): static;

  /**
   * Converts the entity to a WorkflowSnapshot DTO.
   *
   * @return \Drupal\flowdrop_orchestration\DTO\Snapshot\WorkflowSnapshot
   *   The WorkflowSnapshot DTO.
   */
  public function toWorkflowSnapshot(): WorkflowSnapshot;

  /**
   * Updates the entity from a WorkflowSnapshot DTO.
   *
   * @param \Drupal\flowdrop_orchestration\DTO\Snapshot\WorkflowSnapshot $snapshot
   *   The WorkflowSnapshot DTO.
   *
   * @return static
   *   The entity instance.
   */
  public function fromWorkflowSnapshot(WorkflowSnapshot $snapshot): static;

  /**
   * Creates a new entity from a WorkflowSnapshot DTO.
   *
   * @param \Drupal\flowdrop_orchestration\DTO\Snapshot\WorkflowSnapshot $snapshot
   *   The WorkflowSnapshot DTO.
   * @param \Drupal\Core\Entity\EntityStorageInterface $storage
   *   The entity storage for creating the entity.
   *
   * @return static
   *   The new entity instance.
   */
  public static function createFromWorkflowSnapshot(WorkflowSnapshot $snapshot, EntityStorageInterface $storage): static;

}
