<?php

declare(strict_types=1);

namespace Drupal\flowdrop_workflow\Service;

/**
 * Classifies the diff between two FlowDrop Schema snapshot pairs.
 *
 * Both inputs are already annotation-free (the builder strips them at write
 * time) so the differ only deals with contract keys. Property order is
 * normalised before comparison.
 *
 * @api
 */
interface WorkflowSchemaDifferInterface {

  /**
   * Compares two snapshot pairs and classifies the diff.
   *
   * @param array<string, mixed>|null $previousParameterSchema
   *   The previous parameter schema.
   * @param array<string, mixed>|null $newParameterSchema
   *   The new parameter schema.
   * @param array<string, mixed>|null $previousOutputSchema
   *   The previous output schema.
   * @param array<string, mixed>|null $newOutputSchema
   *   The new output schema.
   *
   * @return array{level: 'major'|'minor'|'none', changes: list<array{path: string, kind: string, before: mixed, after: mixed}>}
   *   Classification of the diff.
   */
  public function diff(
    ?array $previousParameterSchema,
    ?array $newParameterSchema,
    ?array $previousOutputSchema,
    ?array $newOutputSchema,
  ): array;

}
