<?php
/**
 * Migration phase: terminal phase marking the job as successfully completed.
 *
 * @package TMDO
 * @since 3.0.1
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Terminal phase — marks the job as successfully completed.
 *
 * Returns 'done' (instead of 'ok') so tick() knows to release the lock and
 * flush the attention cache without scheduling another tick.
 */
class TMDO_Phase_Completed extends TMDO_Migration_Phase_Base {

	/**
	 * Returns the phase slug.
	 *
	 * @return string
	 */
	public function name(): string {
		return 'completed';
	}

	/**
	 * Executes the phase.
	 *
	 * @param array $job Job array (by reference).
	 * @return array{status: 'done'}
	 */
	public function execute( array &$job ): array {
		$job['state']            = 'completed';
		$job['completed_at']     = time();
		$job['overall_progress'] = 100;

		$this->log(
			$job,
			sprintf(
				'✅ Migration complete — ratio %s → %s (-%.0f%%)',
				$job['metrics']['ratio_start'],
				$job['metrics']['ratio_now'],
				( $job['metrics']['ratio_start'] - $job['metrics']['ratio_now'] ) / max( $job['metrics']['ratio_start'], 0.01 ) * 100
			)
		);

		return array( 'status' => 'done' );
	}
}