<?php

declare(strict_types=1);

namespace Drupal\flowdrop_workflow\Service;

use Drupal\flowdrop_workflow\WorkflowDefinitionInterface;

/**
 * Translates between a workflow's interface and its internal node graph.
 *
 * Reads the workflow's input_ports / output_ports exposure maps to:
 * - resolveInputs(): map named inputs onto node-keyed initialData;
 * - extractOutputs(): pick declared outputs out of a completed orchestration's
 *   result set, shaped per output_ports.
 *
 * Both methods preserve backward compatibility with callers that already pass
 * node-keyed data — node-keyed entries are passed through unchanged.
 *
 * @api
 */
interface WorkflowSchemaResolverInterface {

  /**
   * Resolves named workflow inputs to node-keyed initialData.
   *
   * @param \Drupal\flowdrop_workflow\WorkflowDefinitionInterface $workflow
   *   The workflow whose exposure map is consulted.
   * @param array<string, mixed> $namedInputs
   *   Caller-supplied named inputs, e.g. ['message' => 'hello'].
   *
   * @return array<string, array<string, mixed>>
   *   The initialData mapping, e.g. ['chat_input.1' => ['message' => 'hello']].
   */
  public function resolveInputs(
    WorkflowDefinitionInterface $workflow,
    array $namedInputs,
  ): array;

  /**
   * Extracts declared outputs from a completed orchestration result set.
   *
   * @param \Drupal\flowdrop_workflow\WorkflowDefinitionInterface $workflow
   *   The workflow whose exposure map is consulted.
   * @param array<string, array<string, mixed>> $results
   *   Node-keyed results from a completed execution, e.g.
   *   ['chat_output.1' => ['text' => '...']].
   *
   * @return array<string, mixed>
   *   The named outputs, e.g. ['response' => '...']. Empty when no output_ports
   *   are declared.
   */
  public function extractOutputs(
    WorkflowDefinitionInterface $workflow,
    array $results,
  ): array;

}
