<?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;

/**
 * Persists a specific {@see InterruptMessageInterface} shape into an entity.
 *
 * One handler per concrete message class. The
 * {@see InterruptMessageBusInterface} routes by class name via
 * {@see self::supports()}. Register implementations under the
 * `flowdrop_interrupt.message_handler` service tag — the
 * {@see \Drupal\flowdrop_interrupt\DependencyInjection\Compiler\InterruptMessageHandlerPass}
 * validates registrations at container build time, and the bus collects
 * them automatically at runtime.
 *
 * ### Why tagged services and not the plugin system
 *
 * The module's *resolve-side* surface
 * ({@see \Drupal\flowdrop_interrupt\Plugin\InterruptHandler\InterruptHandlerInterface})
 * uses the Drupal plugin system because it needs discovery, alter hooks,
 * caching, and runtime selection of one of N handlers per request. This
 * *create-side* surface needs none of those — it's structural plumbing
 * that fires once when an interrupt is being persisted. Tagged services
 * are correct here because:
 *
 *  - Routing is by concrete message class (not a plugin ID lookup).
 *  - Each handler has its own constructor and DI graph.
 *  - Alter hooks would be a security footgun on the persistence path.
 *  - Validation belongs at container build, not at first dispatch.
 *
 * Naming reflects the boundary: this is `InterruptMessageHandlerInterface`,
 * not `InterruptHandlerInterface` (which is the resolve-side plugin).
 *
 * @api
 */
interface InterruptMessageHandlerInterface {

  /**
   * The concrete message class this handler persists.
   *
   * @return class-string<InterruptMessageInterface>
   *   The message class name.
   */
  public static function supports(): string;

  /**
   * Persists $message with orchestrator-supplied $stamp.
   */
  public function handle(InterruptMessageInterface $message, ExecutionStamp $stamp): FlowDropInterruptInterface;

}
