<?php
/**
 * Storage boundary for the persisted corpus stem document-frequency map.
 *
 * @package Postlinkly
 * @since   1.10.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion;

/**
 * Contract for reading and writing the corpus stem document-frequency map.
 *
 * {@see StemFrequencyRepository} is the production `wpdb`-backed
 * implementation. Decoupling the interface from that implementation lets
 * {@see SuggestionEngine} and {@see StemFrequencyIndexer} stay testable
 * with lightweight fakes, the same way {@see CandidateProvider} keeps the
 * engine free of direct `wpdb` dependencies.
 *
 * @since 1.10.0
 */
interface StemFrequencyRepositoryInterface {

	/**
	 * Returns document-frequency counts for the given stems.
	 *
	 * @since 1.10.0
	 *
	 * @param array<int, string> $stems Stems to look up.
	 *
	 * @return array<string, int> Stem -> document-count map. Stems with no
	 *                            row are absent, not mapped to zero.
	 */
	public function get_many( array $stems ): array;

	/**
	 * Returns the corpus document count.
	 *
	 * @since 1.10.0
	 *
	 * @return int Zero when the map has not been built yet.
	 */
	public function get_document_count(): int;

	/**
	 * Applies incremental +1/-1 adjustments for one indexed post's stems.
	 *
	 * @since 1.10.0
	 *
	 * @param array<string, int> $stem_deltas Stem -> net delta map.
	 * @param int                $doc_delta   Corpus document-count delta.
	 *
	 * @return bool False when a write failed.
	 */
	public function apply_delta( array $stem_deltas, int $doc_delta ): bool;

	/**
	 * Replaces the entire stored frequency map (full rebuild).
	 *
	 * @since 1.10.0
	 *
	 * @param array<string, int> $stem_counts Complete stem -> document-count map.
	 * @param int                $doc_count   Complete corpus document count.
	 *
	 * @return bool False when a write failed.
	 */
	public function replace_all( array $stem_counts, int $doc_count ): bool;
}