<?php

namespace MintyPHP\Service\Audit;

/**
 * Core-side contract for enriching entity audit metadata (created_by, modified_by, etc.)
 * with user display labels and UUIDs.
 *
 * Implemented by the audit module's AuditMetadataEnricher when the module is active.
 * Falls back to NullAuditMetadataEnricher (no-op) when the audit module is disabled.
 */
interface AuditMetadataEnricherInterface
{
    /**
     * Resolve audit user IDs on an entity into display labels and UUIDs.
     *
     * @param array<string,mixed> $entity The entity array (modified in place).
     * @param list<string>        $fields Audit field names to resolve (e.g. 'created_by', 'modified_by').
     */
    public function enrich(array &$entity, array $fields = ['created_by', 'modified_by']): void;
}
