<?php
declare(strict_types=1);

namespace Ekesto\CacheInvalidator\Integrations\Builders;

use Ekesto\CacheInvalidator\BuilderUsageHint;

/**
 * Optional capability for builders that can expose extra scan surface hints.
 *
 * Builders must only declare deterministic candidate container scope and storage
 * locations. Builders must never return resolved usage matches, classifications,
 * fallback decisions, or emitted targets.
 */
interface UsageContainerCapableInterface
{
    /**
     * Return normalized builder usage hints for one changed entity.
     *
     * @param \WP_Post $entity Changed entity being resolved.
     * @return BuilderUsageHint[]
     */
    public function getUsageContainerIds(\WP_Post $entity): array;
}
