<?php
declare(strict_types=1);

namespace Ekesto\CacheInvalidator\Core\Contracts;

use Ekesto\CacheInvalidator\Integrations\Multilingual\LanguageResolverInterface;

/**
 * Multilingual provider seam.
 *
 * Lite ships a no-op default; the premium build registers a real provider via
 * {@see \Ekesto\CacheInvalidator\Core\Multilingual\MultilingualProviderRegistry}.
 *
 * Only the two premium concerns live behind this seam: resolving the active
 * multilingual resolver (plugin detection + adapters + the resolver filter) and
 * the fanout-mode override filter. Generic fanout math, URL expansion, object
 * sibling lookup, and the resolver contracts stay Lite-safe and are NOT part of
 * this interface.
 */
interface MultilingualProviderInterface
{
    /**
     * Resolve the active multilingual resolver, or null when none is available.
     *
     * @return LanguageResolverInterface|null
     */
    public function createResolver(): ?LanguageResolverInterface;

    /**
     * Apply any premium override to the computed fanout mode.
     *
     * @param string              $mode    Base fanout mode (one of FanoutPolicy::MODE_*).
     * @param array<string,mixed> $context Runtime context.
     * @return string Possibly-overridden fanout mode.
     */
    public function filterFanoutMode(string $mode, array $context): string;
}
