<?php

declare(strict_types=1);

namespace Drupal\flowdrop_node_type\Service;

/**
 * Generates a flowdrop_node_type config entity from a workflow node.
 *
 * Used by workflow import: a portable workflow file carries node metadata but
 * not the flowdrop_node_type config entities the runtime requires
 * (NodeRuntimeService loads the entity by data.metadata.node_type_id to
 * resolve the processor). When the backing processor plugin is installed but
 * no node type
 * is registered, this service mints one.
 *
 * Generation is a reconciliation, never a copy: the authoritative parameter and
 * output *sets* (and their types) come from the live plugin's
 * getParameterSchema()/getOutputSchema(); the authoring flags (which params are
 * connectable/configurable, which outputs are exposed) are reconstructed from
 * the node's embedded metadata, which is the inverse of the forward transform
 * in NodesController::buildNodeData(). Anything the metadata references that
 * the live plugin cannot back is rejected — a file can never widen the
 * contract.
 *
 * Generation is strictly additive: an existing node type is never overwritten.
 *
 * @internal This service is not part of the public API and may change without
 *   notice.
 */
interface NodeTypeGeneratorInterface {

  /**
   * Generates the node type for a single workflow node, if absent.
   *
   * @param array<string, mixed> $node
   *   A workflow node as stored on the entity (with data.metadata).
   *
   * @return \Drupal\flowdrop_node_type\Service\NodeTypeGenerationResult
   *   The outcome: created, skipped (already present), or rejected.
   */
  public function generate(array $node): NodeTypeGenerationResult;

}
