<?php

declare(strict_types=1);

namespace Drupal\flowdrop_orchestration\DTO;

/**
 * Minimal contract for a resolved interrupt's resume payload.
 *
 * Used by {@see \Drupal\flowdrop\Plugin\FlowDropNodeProcessor\ResumableNodeProcessorInterface}
 * so the resume hook can be defined in flowdrop core without flowdrop_runtime
 * depending on flowdrop_interrupt.
 *
 * The concrete implementation lives in flowdrop_interrupt's
 * {@see \Drupal\flowdrop_interrupt\Entity\FlowDropInterruptInterface}, which
 * extends this interface. Nodes that need richer access (schema, context,
 * options) can downcast and read from the entity directly — at the cost of
 * a hard dependency on flowdrop_interrupt.
 *
 * @api
 */
interface ResolvedInterruptInterface {

  /**
   * The unique identifier of the interrupt.
   */
  public function getInterruptId(): string;

  /**
   * The ID of the job that raised this interrupt, if any.
   *
   * An interrupt resolution is the answer to one specific question asked by
   * one specific job. Consumers MUST NOT honor a resolved interrupt for a
   * job other than this one — job metadata can carry a foreign interrupt
   * UUID (loop-iteration clones, retries, copies), and resuming from it
   * would replay another execution's answer.
   */
  public function getJobId(): ?int;

  /**
   * The resolved response payload.
   *
   * Whatever the handler wrote into response_data when the interrupt
   * resolved — typically the user's input for HITL interrupts, or the
   * sub-workflow's outputs for cascade-resolved operational interrupts.
   *
   * @return mixed
   *   The response payload. Shape is type-specific.
   */
  public function getResponseData(): mixed;

  /**
   * The UID that resolved the interrupt, if any.
   *
   * NULL for anonymous resolutions, runtime-driven resolutions
   * (PipelineCompletedSubscriber, scheduled sweepers), and webhook-driven
   * resolutions without authenticated user context.
   */
  public function getResolvedBy(): ?int;

  /**
   * The unix timestamp when the interrupt was resolved.
   *
   * NULL only on entities loaded before resolution completes — pending
   * interrupts have no resolution time.
   */
  public function getResolvedAt(): ?int;

}
