<?php

declare(strict_types=1);

namespace Drupal\flowdrop_interrupt\Message;

use Drupal\flowdrop_interrupt\Enum\InterruptType;

/**
 * Interrupt message that resolves when another interrupt resolves.
 *
 * Use this when a node's pause is gated on another asynchronous unit of
 * work that's already represented by an interrupt entity. The canonical
 * case is a parent workflow waiting for a dispatched sub-workflow — the
 * sub-workflow gets a {@see InterruptType::PipelineCompletion} sentinel
 * interrupt, and the parent's message links to it.
 *
 * When the linked interrupt resolves, the cascade subscriber resolves this
 * one with the same response payload.
 *
 * Example:
 * @code
 * throw new InterruptRequiredException(new LinkedInterruptMessage(
 *   type: InterruptType::WorkflowExecution,
 *   message: 'Waiting on dispatched workflow',
 *   linkedInterruptId: $sentinelUuid,
 * ));
 * @endcode
 *
 * @api
 */
final class LinkedInterruptMessage extends AbstractInterruptMessage {

  /**
   * Constructs a new LinkedInterruptMessage.
   *
   * @param \Drupal\flowdrop_interrupt\Enum\InterruptType $type
   *   The interrupt type.
   * @param string $message
   *   Human-readable description of the interrupt.
   * @param string $linkedInterruptId
   *   UUID of the interrupt this one is gated on. Validated as an
   *   entity_reference when persisted.
   * @param array<string, mixed> $context
   *   Opaque payload — never a lookup key.
   */
  public function __construct(
    InterruptType $type,
    string $message,
    public readonly string $linkedInterruptId,
    array $context = [],
  ) {
    parent::__construct($type, $message, $context);
  }

}
