<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Service\Storage;

use Drupal\flowdrop_orchestration\Service\Orchestrator\OrchestratorInterface;

/**
 * Registry mapping pipeline bundle names to their storage implementations.
 *
 * @api
 */
interface PipelineStorageRegistryInterface {

  /**
   * The DB-backed default pipeline bundle.
   */
  const BUNDLE_DEFAULT = 'default';

  /**
   * The ephemeral in-memory pipeline bundle used by SynchronousOrchestrator.
   *
   * Note: the corresponding service tag uses the literal string value; PHP
   * constants cannot be referenced in YAML service definitions.
   */
  const BUNDLE_IN_MEMORY = 'in_memory';

  /**
   * Returns the pipeline storage for a given bundle.
   *
   * @throws \InvalidArgumentException
   *   If no storage is registered for the given bundle name.
   */
  public function getStorage(string $bundle): PipelineStorageInterface;

  /**
   * Returns the pipeline bundle preferred by the given orchestrator.
   *
   * Resolves via PipelineAwareOrchestratorInterface when implemented;
   * falls back to 'default' for orchestrators that do not declare a preference.
   *
   * @param \Drupal\flowdrop_orchestration\Service\Orchestrator\OrchestratorInterface $orchestrator
   *   The orchestrator instance.
   *
   * @return string
   *   The pipeline bundle name.
   */
  public function getBundleForOrchestrator(OrchestratorInterface $orchestrator): string;

  /**
   * Returns the pipeline storage preferred by the given orchestrator.
   *
   * Convenience wrapper over getBundleForOrchestrator() + getStorage().
   *
   * @param \Drupal\flowdrop_orchestration\Service\Orchestrator\OrchestratorInterface $orchestrator
   *   The orchestrator instance.
   *
   * @return \Drupal\flowdrop_runtime\Service\Storage\PipelineStorageInterface
   *   The storage for the orchestrator's preferred bundle.
   *
   * @throws \InvalidArgumentException
   *   If no storage is registered for the resolved bundle.
   */
  public function getStorageForOrchestrator(OrchestratorInterface $orchestrator): PipelineStorageInterface;

}
