<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Service;

use Drupal\flowdrop_interrupt\DTO\ExecutionStamp;
use Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface;
use Drupal\flowdrop_interrupt\Message\InterruptMessageInterface;

/**
 * Dispatches an {@see InterruptMessageInterface} to its registered handler.
 *
 * New message shapes drop in as `flowdrop_interrupt.message_handler`-tagged
 * services with no central edit — the
 * {@see \Drupal\flowdrop_interrupt\DependencyInjection\Compiler\InterruptMessageHandlerPass}
 * enforces uniqueness and interface conformance at container build time.
 *
 * @api
 */
interface InterruptMessageBusInterface {

  /**
   * Persists $message with the supplied execution stamp.
   *
   * @throws \LogicException
   *   If no handler is registered for the concrete message class.
   */
  public function dispatch(
    InterruptMessageInterface $message,
    ExecutionStamp $stamp,
  ): FlowDropInterruptInterface;

}
