<?php
/**
 * Contract for adding suggestions the lexical gate excluded.
 *
 * @package Postlinkly
 * @since   1.18.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion\Enhancer;

use Postlinkly\Post\PostModel;
use Postlinkly\Suggestion\Candidate;
use Postlinkly\Suggestion\LightCandidate;
use Postlinkly\Suggestion\SuggestionModel;
use Postlinkly\Text\PhraseModel;

/**
 * Supplies extra suggestions for candidates the suggestion engine's
 * title-overlap gate turned away, merged in before ranking.
 *
 * The engine never builds one itself. An add-on provides it through the
 * `postlinkly_candidate_injector` filter, so the keyword engine runs
 * unchanged when none is present.
 *
 * Implementations must fail open: return an empty array rather than throw,
 * because the suggestions the engine already produced must survive any
 * failure here.
 *
 * @since 1.18.0
 */
interface CandidateInjectorInterface {

	/**
	 * Returns new suggestions for candidates the lexical gate excluded.
	 *
	 * Must never mutate $suggestions; return only the newly-constructed
	 * entries, which the engine merges into its own list.
	 *
	 * @since 1.18.0
	 *
	 * @param array<int, PhraseModel>     $phrases          Source phrases, the same list
	 *                                                       the main scoring loop used.
	 * @param array<int, SuggestionModel> $suggestions      Suggestions the main loop already
	 *                                                       produced, so their targets are
	 *                                                       not considered twice.
	 * @param array<int, LightCandidate>  $light_candidates Full candidate corpus, identity
	 *                                                       and title only.
	 * @param PostModel                   $source           Source post.
	 * @param callable(array<int,int>): array<int, Candidate> $hydrate Returns fully-tokenised
	 *        candidates for the given post ids. Call it only for the few candidates
	 *        that need an anchor built, never for the whole corpus.
	 *
	 * @return array<int, SuggestionModel> Newly-constructed suggestions to merge in.
	 */
	public function inject_candidates( array $phrases, array $suggestions, array $light_candidates, PostModel $source, callable $hydrate ): array;
}