<?php
/**
 * Identity-and-title-only candidate description for two-phase loading.
 *
 * @package Postlinkly
 * @since   1.10.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion;

use Postlinkly\Post\PostModel;

/**
 * Identity-and-title-only candidate description for two-phase loading.
 *
 * Phase 1 of the engine's two-phase candidate loading ({@see
 * CandidateProvider::get_light_candidates_for()}) returns these instead of
 * fully-tokenised {@see Candidate} instances, because building a
 * `Candidate` requires reading and stemming `post_content` — the exact
 * per-candidate cost the phase split exists to avoid paying for the whole
 * corpus.
 *
 * A dedicated type (rather than a `Candidate` with an empty `word_counts`)
 * exists so "this candidate's content was never read" can never be
 * confused with "this candidate's content tokenised to zero words" —
 * two states that mean very different things downstream but would be
 * bitwise identical if both were represented as an empty array on the
 * same class.
 *
 * Properties are public for compactness; do not modify them after
 * construction.
 *
 * @since 1.10.0
 */
final class LightCandidate {

	/**
	 * The candidate post or term, with title/status/slug populated but no
	 * content-derived data.
	 *
	 * @var PostModel
	 */
	public PostModel $post;

	/**
	 * Pre-stemmed, space-joined target keywords.
	 *
	 * Carried on the light candidate (not deferred to hydration) so a
	 * keyword-only match — an owner-declared target keyword with no title
	 * overlap — can be detected during the engine's gating pass without
	 * forcing every candidate to hydrate just to find the few with
	 * keywords set.
	 *
	 * @var array<int, string>
	 */
	public array $target_keywords;

	/**
	 * @since 1.10.0
	 *
	 * @param PostModel          $post            The candidate post or term.
	 * @param array<int, string> $target_keywords Optional. Stemmed target
	 *                                            keywords. Default [].
	 */
	public function __construct( PostModel $post, array $target_keywords = array() ) {
		$this->post            = $post;
		$this->target_keywords = $target_keywords;
	}
}