<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Service\Runtime;

use Drupal\flowdrop\DTO\Tool\ToolCollectionInterface;
use Drupal\flowdrop_pipeline\Entity\FlowDropPipelineRuntimeInterface;
use Drupal\flowdrop_runtime\DTO\Compiler\DependencyGraph;
use Drupal\flowdrop_runtime\DTO\Runtime\NodeExecutionContext;

/**
 * Projects the tools wired to a node into a {@see ToolCollectionInterface}.
 *
 * Resolves a consumer node's outgoing `tool_availability` edges into a narrow,
 * just-in-time description of each connected tool (name, description, parameter
 * schema) plus a scoped invoker that enforces authorization. Called by an
 * orchestrator (which owns the graph) right before a tool-consuming node runs.
 *
 * @see \Drupal\flowdrop\DTO\Tool\ToolCollectionInterface
 * @see \Drupal\flowdrop\Service\Tool\ToolInvokerInterface
 *
 * @internal
 *   Runtime wiring detail invoked by orchestrators; not a stable API.
 */
interface ToolProjectorInterface {

  /**
   * Projects the tools available to a consumer node.
   *
   * @param string $consumerNodeId
   *   The node whose tools to resolve.
   * @param \Drupal\flowdrop_runtime\DTO\Compiler\DependencyGraph $graph
   *   The compiled dependency graph.
   * @param \Drupal\flowdrop_runtime\DTO\Runtime\NodeExecutionContext $context
   *   The current execution context.
   * @param string $executionId
   *   The execution ID, needed to run tool nodes on demand.
   * @param \Drupal\flowdrop_pipeline\Entity\FlowDropPipelineRuntimeInterface|null $pipeline
   *   The LIVE pipeline instance of the current run. When given, every tool
   *   invocation is recorded as a normal pipeline job item (a flowdrop_job
   *   appended to this instance, with JobCompletedEvent dispatched); when
   *   NULL, tool calls run unrecorded (legacy behaviour).
   *
   * @return \Drupal\flowdrop\DTO\Tool\ToolCollectionInterface
   *   The available tools (empty when the node has no tool_availability edges).
   */
  public function project(
    string $consumerNodeId,
    DependencyGraph $graph,
    NodeExecutionContext $context,
    string $executionId,
    ?FlowDropPipelineRuntimeInterface $pipeline = NULL,
  ): ToolCollectionInterface;

}
