<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Service;

use Drupal\flowdrop_interrupt\DTO\InterruptCreationData;
use Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface;

/**
 * Narrow persistence-side contract for interrupt entities.
 *
 * Implementations write the supplied {@see InterruptCreationData} as a
 * FlowDropInterrupt entity, dispatching the InterruptCreatedEvent. This is
 * an `@internal` plumbing surface — application code should use the
 * {@see InterruptMessageBusInterface} with an
 * {@see \Drupal\flowdrop_interrupt\Message\InterruptMessageInterface}
 * instead. The
 * bus's per-shape handlers depend on this contract to do the actual write.
 *
 * @internal
 */
interface InterruptFactoryInterface {

  /**
   * Persists a new interrupt from a value-object description.
   *
   * @param \Drupal\flowdrop_interrupt\DTO\InterruptCreationData $data
   *   The interrupt to persist.
   *
   * @return \Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface
   *   The persisted interrupt.
   */
  public function create(InterruptCreationData $data): FlowDropInterruptInterface;

}
