<?php
/**
 * Contract for suggestion enhancers (BYOK AI seam).
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion\Enhancer;

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

/**
 * Contract for suggestion enhancers.
 *
 * An enhancer receives the ranked suggestion list produced by the engine
 * and may reorder, filter, or augment it before the result is returned
 * to the caller. Enhancers run after the ranker, in registration order.
 *
 * v1.0 ships this interface and zero implementations. v1.x adds
 * `OpenAiByokEnhancer` as a separate class that reads the user's own
 * API key from settings. The engine calls `enhance()` after ranking;
 * if no enhancers are registered, the call is a no-op.
 *
 * Implementations must be:
 *
 *   - Deterministic when no external service is involved.
 *   - Gracefully degrading: if the external service is unavailable,
 *     return the input list unchanged rather than throwing.
 *   - Side-effect free with respect to the database.
 *
 * @since 1.0.0
 */
interface EnhancerInterface {

	/**
	 * Enhances a ranked suggestion list.
	 *
	 * @since 1.0.0
	 *
	 * @param array<int, SuggestionModel> $suggestions Ranked suggestions from the engine.
	 * @param PostModel                   $source      The source post being analysed.
	 *
	 * @return array<int, SuggestionModel> The (possibly reordered/filtered/augmented) list.
	 */
	public function enhance( array $suggestions, PostModel $source ): array;
}