<?php

declare(strict_types=1);

namespace Drupal\flowdrop_pipeline\Entity;

use Drupal\Core\Entity\ContentEntityInterface;
use Drupal\Core\Entity\EntityChangedInterface;
use Drupal\Core\Entity\EntityStorageInterface;
use Drupal\user\EntityOwnerInterface;

/**
 * Defines the flowdrop pipeline entity class.
 *
 * @internal
 *   This class is not part of the public API and may change without notice.
 */
interface FlowDropPipelineInterface extends FlowDropPipelineRuntimeInterface, ContentEntityInterface, EntityChangedInterface, EntityOwnerInterface {

  /**
   * {@inheritdoc}
   */
  public function preSave(EntityStorageInterface $storage);

  /**
   * Get the playground session this pipeline belongs to.
   *
   * @return string|null
   *   The session entity ID, or NULL if this pipeline is not bound to a
   *   playground session.
   */
  public function getSessionId(): ?string;

  /**
   * Set the playground session this pipeline belongs to.
   *
   * Treat as immutable post-creation — pipelines do not move between
   * sessions.
   *
   * @param string|null $session_id
   *   The session entity ID, or NULL to unbind.
   *
   * @return static
   */
  public function setSessionId(?string $session_id): static;

  /**
   * Get the pipeline that spawned this one.
   *
   * @return string|null
   *   The parent pipeline id, or NULL for a top-level run.
   */
  public function getParentPipelineId(): ?string;

  /**
   * Set the pipeline that spawned this one.
   *
   * @param string|null $parent_pipeline_id
   *   The parent pipeline id, or NULL for a top-level run.
   *
   * @return static
   */
  public function setParentPipelineId(?string $parent_pipeline_id): static;

  /**
   * Get the top-level pipeline of this run.
   *
   * Always populated on a saved pipeline: a root pipeline stores its own id
   * (stamped on insert), a nested one inherits its parent's root.
   *
   * @return string|null
   *   The root pipeline id.
   */
  public function getRootPipelineId(): ?string;

  /**
   * Set the top-level pipeline of this run.
   *
   * Leave unset on a new top-level pipeline — postSave() will self-root it.
   *
   * @param string|null $root_pipeline_id
   *   The root pipeline id.
   *
   * @return static
   */
  public function setRootPipelineId(?string $root_pipeline_id): static;

  /**
   * Get the UUID of the interrupt this pipeline is paused on.
   *
   * @return string|null
   *   The interrupt UUID, or NULL if this pipeline is not paused.
   */
  public function getPendingInterruptId(): ?string;

  /**
   * Set (or clear) the pending interrupt UUID.
   *
   * @param string|null $interrupt_id
   *   The interrupt UUID, or NULL to clear (pipeline no longer paused).
   *
   * @return static
   */
  public function setPendingInterruptId(?string $interrupt_id): static;

  /**
   * Get the string form of the pending interrupt's type.
   *
   * @return string|null
   *   The InterruptType value, or NULL if not paused.
   */
  public function getPendingInterruptType(): ?string;

  /**
   * Set (or clear) the pending interrupt type.
   *
   * @param string|null $type
   *   The InterruptType value, or NULL to clear.
   *
   * @return static
   */
  public function setPendingInterruptType(?string $type): static;

}
