<?php

declare(strict_types=1);

namespace Drupal\flowdrop_orchestration\Attribute;

use Drupal\Component\Plugin\Attribute\Plugin;
use Drupal\Core\StringTranslation\TranslatableMarkup;

/**
 * Attribute for Orchestrator plugins.
 *
 * This attribute provides plugin discovery metadata for FlowDrop orchestrators.
 * Orchestrators handle how workflows are executed (synchronously,
 * asynchronously, with state management, etc.).
 *
 * Example usage:
 * @code
 * #[Orchestrator(
 *   id: "my_orchestrator",
 *   label: new TranslatableMarkup("My Orchestrator"),
 *   description: "Custom orchestrator with special features",
 *   capabilities: ["synchronous_execution", "retry_support"],
 * )]
 * class MyOrchestrator extends OrchestratorPluginBase {
 *   // ...
 * }
 * @endcode
 *
 * @see \Drupal\flowdrop_orchestration\Plugin\Orchestrator\OrchestratorPluginInterface
 * @see \Drupal\flowdrop_orchestration\Plugin\Orchestrator\OrchestratorPluginBase
 *
 * @api
 */
#[\Attribute(\Attribute::TARGET_CLASS)]
final class Orchestrator extends Plugin {

  /**
   * Constructs a new Orchestrator attribute.
   *
   * @param string $id
   *   The plugin ID (e.g., "synchronous", "asynchronous", "stategraph").
   * @param \Drupal\Core\StringTranslation\TranslatableMarkup $label
   *   The human-readable label for the orchestrator.
   * @param string $description
   *   A description of what this orchestrator does.
   * @param array<int, string> $capabilities
   *   List of capability names this orchestrator supports. Common capabilities:
   *   - synchronous_execution: Can execute in current request
   *   - async_execution: Can execute via background queue
   *   - parallel_execution: Can run multiple jobs simultaneously
   *   - pipeline_based: Uses pipeline entities for execution
   *   - job_tracking: Tracks individual job status
   *   - stateful: Maintains execution state with checkpointing
   *   - retry_support: Can retry failed operations
   *   - error_recovery: Can recover from errors gracefully
   *   - interrupt_support: Supports execution interruption
   *   - checkpointing: Creates state checkpoints during execution.
   * @param class-string|null $deriver
   *   (optional) The deriver class for dynamic plugin definitions.
   */
  public function __construct(
    public readonly string $id,
    public readonly TranslatableMarkup $label,
    public readonly string $description = "",
    public readonly array $capabilities = [],
    public readonly ?string $deriver = NULL,
  ) {}

}
