<?php
/**
 * Candidate pool enhancer contract.
 *
 * @package Postlinkly
 * @since   1.2.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion\Enhancer;

use Postlinkly\Post\PostModel;
use Postlinkly\Suggestion\SuggestionModel;

/**
 * Contract for enhancers that operate on the over-fetched candidate pool
 * before the final suggestion limit is applied.
 *
 * Pool enhancers run before anchor deduplication so they can reorder a
 * larger candidate set. This is the seam for semantic reranking — the
 * reranker receives an over-fetched pool, reorders by similarity, and
 * then the engine deduplicates and truncates to the requested limit.
 *
 * @since 1.2.0
 */
interface CandidatePoolEnhancerInterface {

	/**
	 * Enhances a candidate pool.
	 *
	 * @since 1.2.0
	 *
	 * @param array<int, SuggestionModel> $candidates Over-fetched candidate pool.
	 * @param PostModel                   $source     The source post being analysed.
	 *
	 * @return array<int, SuggestionModel> Reordered/filtered pool.
	 */
	public function enhance_pool( array $candidates, PostModel $source ): array;
}