<?php

declare(strict_types=1);

namespace App\Domain\Audit;

/**
 * Writes one row to `audit_log` per successful state-changing operation.
 *
 * Implementations MUST swallow infra failures (DB hiccup, OOM during
 * JSON encode) and log them — emitting an audit row is observability,
 * not a transactional invariant. A failed emit must never propagate
 * an exception that aborts the originating request.
 */
interface AuditEmitter
{
    /**
     * @param array<string, mixed> $payload Free-form event payload, JSON-encoded into details_json.
     *     MUST NOT contain raw secrets (raw tokens, passwords).
     * @param string|null $entityLabel Human-readable identifier (name, slug, IP, CIDR, prefix).
     *     Frozen at write time — later renames don't rewrite history. Pass null only when no
     *     meaningful label exists (system-wide actions like maintenance.purged).
     */
    public function emit(
        string $action,
        ?string $entityType,
        int|string|null $entityId,
        array $payload,
        AuditContext $context,
        ?string $entityLabel = null,
    ): void;
}