<?php

declare(strict_types=1);

namespace Drupal\flowdrop_workflow\Service;

use Drupal\flowdrop_workflow\FlowDropWorkflowInterface;

/**
 * Service that rebuilds + versions a workflow's schema snapshot on save.
 *
 * The hook layer ({@see \Drupal\flowdrop_workflow\Hook\Hooks}) calls this
 * from `hook_ENTITY_TYPE_presave`; the entity itself stays free of service
 * lookups.
 *
 * @api
 */
interface WorkflowSchemaSnapshotterInterface {

  /**
   * Rebuilds the workflow's snapshot when the exposure map changed.
   *
   * @param \Drupal\flowdrop_workflow\FlowDropWorkflowInterface $workflow
   *   The workflow being saved. Mutated in place: parameter_schema,
   *   output_schema, and schema_version are written when a rebuild fires.
   * @param \Drupal\flowdrop_workflow\FlowDropWorkflowInterface|null $original
   *   The pre-save entity, if this is an update. NULL for inserts.
   * @param bool $forced
   *   When TRUE, skip the exposure-map deep-equality short-circuit. Used by
   *   the drift-banner "Refresh schema" flow to rebuild even when the
   *   exposure map didn't change.
   */
  public function rebuildIfNeeded(
    FlowDropWorkflowInterface $workflow,
    ?FlowDropWorkflowInterface $original,
    bool $forced,
  ): void;

}
