<?php

declare(strict_types=1);

namespace Drupal\flowdrop_workflow\Service;

use Drupal\flowdrop_workflow\FlowDropWorkflowInterface;

/**
 * Builds a FlowDrop Schema snapshot from a workflow's exposure map.
 *
 * Walks a list of port exposures, looks up each source port's schema
 * fragment from its node processor plugin, strips annotations to produce
 * the closed FlowDrop Schema contract subset, and assembles the snapshot
 * persisted on the workflow config entity.
 *
 * @api
 */
interface WorkflowSchemaBuilderInterface {

  /**
   * Builds a parameter or output schema snapshot from an exposure list.
   *
   * @param \Drupal\flowdrop_workflow\FlowDropWorkflowInterface $workflow
   *   The workflow being saved (used for cycle detection and logging).
   * @param list<array{name: string, node_id: string, port: string}> $ports
   *   The exposure entries.
   * @param 'input'|'output' $direction
   *   Which side of the schema this builds.
   * @param array<string, true> $visited
   *   Workflow IDs already on the current build path (recursion guard).
   *
   * @return array<string, mixed>
   *   The snapshot — JSON Schema-shaped, annotation-free. Returns an empty
   *   object schema (`['type' => 'object', 'properties' => []]`) when no
   *   entries resolve.
   */
  public function build(
    FlowDropWorkflowInterface $workflow,
    array $ports,
    string $direction,
    array &$visited = [],
  ): array;

  /**
   * Strips annotation keys and out-of-subset keys from a JSON Schema fragment.
   *
   * Recurses into `properties` and `items`. Preserves only the FlowDrop
   * Schema contract subset:
   * type, enum, format, default, required, properties, items, minimum,
   * maximum, minLength, maxLength, pattern.
   *
   * @param array<string, mixed> $fragment
   *   The source fragment (e.g. from $plugin->getParameterSchema()).
   *
   * @return array<string, mixed>
   *   The filtered fragment.
   */
  public function pickContractKeys(array $fragment): array;

}
