<?php
/**
 * Contract for sources of suggestion candidates.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion;

use Postlinkly\Post\PostModel;

/**
 * Contract for sources of suggestion candidates.
 *
 * The {@see SuggestionEngine} asks a CandidateProvider for the corpus of
 * potential target posts each time `get_suggestions()` runs. Decoupling
 * the corpus source from the engine lets the engine stay free of
 * WordPress and `wpdb` calls — the production provider queries the post
 * repository, while tests pass in deterministic fixtures.
 *
 * Implementations are expected to:
 *
 *   - Exclude the source post / term from every method's result. The
 *     engine does not double-check this — providers must not produce
 *     self-matches.
 *   - Be reasonably cheap to call. The engine calls these once per
 *     source post, but on a large site that's still many calls.
 *
 * Loading is two-phase as of 1.10.0: {@see get_light_candidates_for()}
 * hands back every candidate's identity and title only, cheaply enough to
 * run over the whole corpus with no upper bound; {@see hydrate()} then
 * builds fully-tokenised {@see Candidate} instances, but only for the ids
 * the engine's title/keyword gate actually admitted. `get_candidates_for()`
 * remains for fixtures and callers that still want the whole corpus
 * fully-tokenised in one call; the engine itself no longer uses it. A
 * provider whose data is cheap enough that a phase split buys nothing
 * (e.g. one with no content to tokenise at all) may implement `hydrate()`
 * as a passthrough over the same data `get_light_candidates_for()`
 * already has — document that choice in the provider's own class
 * docblock rather than reintroducing a single-method interface.
 *
 * @since 1.0.0
 * @since 1.10.0 Added get_light_candidates_for() and hydrate() for
 *        two-phase candidate loading. get_candidates_for() is no longer
 *        the engine's primary path but remains part of the contract.
 */
interface CandidateProvider {

	/**
	 * Returns the fully-tokenised candidate corpus for a source post.
	 *
	 * @since 1.0.0
	 *
	 * @param PostModel $source The post or term being analysed.
	 *
	 * @return array<int, Candidate> Candidates excluding the source itself.
	 */
	public function get_candidates_for( PostModel $source ): array;

	/**
	 * Returns every candidate's identity and title, without content.
	 *
	 * Phase 1 of two-phase loading: cheap enough to run over the whole
	 * corpus, because it never reads or tokenises `post_content`. The
	 * engine gates on these (title overlap and target-keyword matching
	 * need nothing more), then asks {@see hydrate()} for the survivors.
	 *
	 * @since 1.10.0
	 *
	 * @param PostModel $source The post or term being analysed.
	 *
	 * @return array<int, LightCandidate> Light candidates excluding the
	 *                                    source itself.
	 */
	public function get_light_candidates_for( PostModel $source ): array;

	/**
	 * Returns fully-tokenised candidates for the given post ids.
	 *
	 * Phase 2 of two-phase loading: this is where `post_content` is read
	 * and stemmed, so callers must only ever pass ids that already
	 * survived the engine's gate — never the whole corpus, or the cost
	 * this split exists to avoid is paid anyway.
	 *
	 * A post id with no meaningful words (empty title and content) is
	 * omitted from the result, matching {@see get_candidates_for()}'s
	 * long-standing "not a candidate at all" rule — callers must not
	 * assume every requested id comes back.
	 *
	 * @since 1.10.0
	 *
	 * @param array<int, int> $post_ids Post ids to hydrate. Passing an
	 *                                  empty array must return an empty
	 *                                  array without querying anything.
	 *
	 * @return array<int, Candidate> Fully-tokenised candidates, in no
	 *                                guaranteed order, and possibly fewer
	 *                                than the ids requested.
	 */
	public function hydrate( array $post_ids ): array;
}