<?php
declare(strict_types=1);

namespace Ekesto\CacheInvalidator\Core\Contracts;

/**
 * Relationship propagation provider seam.
 *
 * Lite ships a no-op default implementation; the premium build registers a real
 * provider through {@see \Ekesto\CacheInvalidator\Core\Relationships\RelationshipProviderRegistry}.
 *
 * Only relationship *propagation* lives behind this seam. Settings/config graph
 * reads (configured/watched post types) and pure cycle validation stay Lite-safe
 * and are NOT part of this contract.
 */
interface RelationshipProviderInterface
{
    /**
     * Resolve configured host post types affected by a trigger post type.
     *
     * @param string $triggerPostType
     * @return string[]
     */
    public function resolveAffectedHosts(string $triggerPostType): array;

    /**
     * Resolve ordered propagation edges [from_pt, to_pt] in BFS order.
     *
     * @param string $triggerPostType
     * @return array<int,array{0:string,1:string}>
     */
    public function resolveRelationshipEdges(string $triggerPostType): array;

    /**
     * Find host post IDs that reference a given related post.
     *
     * @param string $hostPostType    The post type to search.
     * @param string $relatedPostType The post type of the changed entity.
     * @param int    $relatedId       The ID of the changed related post.
     * @return int[]
     */
    public function findHostPostIds(string $hostPostType, string $relatedPostType, int $relatedId): array;
}
