<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Plugin\InterruptHandler;

use Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface;

/**
 * Marks an interrupt handler as queue-resolved.
 *
 * Plugins implementing this interface declare a Drupal queue name; a queue
 * worker picks up the deferred work and resolves the interrupt with its
 * result. The worker side calls `InterruptManager::resolveInterrupt()`
 * directly — this interface only provides the metadata needed to enqueue.
 *
 * Use for: long-running data transforms, batched LLM jobs, anything that
 * needs to run outside the workflow's request context.
 *
 * @api
 */
interface QueueDelegationInterruptHandlerInterface extends InterruptHandlerInterface {

  /**
   * The Drupal queue name to push work to.
   */
  public function getQueueName(): string;

  /**
   * Produces the payload to enqueue for this interrupt.
   *
   * The queue worker receives this payload and uses it to execute the
   * deferred work.
   *
   * @return array<string, mixed>
   *   The payload to enqueue.
   */
  public function describeWork(FlowDropInterruptInterface $interrupt): array;

}
