<?php

declare(strict_types=1);

namespace Drupal\flowdrop_workflow\Service;

use Drupal\flowdrop_workflow\FlowDropWorkflowInterface;

/**
 * Detects drift between a workflow snapshot and live plugin schemas.
 *
 * Detects drift between a workflow's stored snapshot and the current live
 * plugin schemas behind its exposure map.
 *
 * Read-only — runs without modifying the workflow or its snapshot. Surfaced
 * in the workflow form's "Refresh schema" banner and intended for CI use
 * via drush.
 *
 * @api
 */
interface WorkflowDriftDetectorInterface {

  /**
   * Returns exposure entries whose live source-port schema differs.
   *
   * Compares each exposure entry against the stored snapshot.
   *
   * @param \Drupal\flowdrop_workflow\FlowDropWorkflowInterface $workflow
   *   The workflow to inspect.
   *
   * @return list<array{side: 'input'|'output', name: string, node_id: string, port: string, stored: array<string, mixed>|null, live: array<string, mixed>|null}>
   *   One entry per drifted exposure. Empty when the snapshot is in sync.
   */
  public function detectDrift(FlowDropWorkflowInterface $workflow): array;

}
