<?php
/**
 * One structured fact about what happened.
 *
 * @package MazeAi
 * @since   0.1.0
 */

declare(strict_types=1);

namespace MazeAi\Kernel\Support;

defined('ABSPATH') || exit;

/**
 * The closed, versioned event vocabulary (decision 034). Payloads keep only the allow-listed keys below: ids,
 * counts, schema sizes, codes, durations, model and tool names. Never message text, tool arguments or results, keys
 * or provider state; anything else passed in is dropped.
 *
 * @since 0.1.0
 */
final class Event
{
    public const VERSION = 1;

    private const INTEGER_KEYS = [
        'session', 'user', 'step', 'tokens_in', 'tokens_out', 'ms', 'tool_count', 'tool_schema_bytes', 'bytes',
        'kept', 'dropped', 'attempt', 'retry_after', 'change', 'est_tokens',
    ];

    private const LIST_KEYS = ['tools', 'tools_skipped', 'fields'];

    private const MAX_LIST_ITEMS = 20;

    private const MAX_STRING_BYTES = 128;

    public const NAMES = [
        'run.started', 'step.started', 'model.called', 'step.retry', 'tool.decided', 'tool.executed',
        'context.trimmed', 'step.finished', 'run.finished', 'policy.denied',
        'change.recorded', 'change.undone', 'module.failed', 'studio.generated', 'studio.saved',
        'session.created', 'session.updated', 'session.trashed', 'session.restored', 'session.archived',
        'settings.updated', 'job.started', 'job.finished',
    ];

    public const KEYS = [
        'session', 'run', 'step', 'user', 'agent', 'job', 'model', 'provider', 'tokens_in', 'tokens_out', 'ms', 'finish',
        'tool', 'tools', 'tools_skipped', 'tool_count', 'tool_schema_bytes', 'effect', 'code', 'status', 'bytes', 'action', 'resource', 'reason', 'kept', 'dropped', 'call',
        'est_tokens', 'attempt', 'retry_after', 'change', 'tainted', 'module', 'via', 'template', 'fields',
    ];

    /** @var array<string, mixed> */
    public readonly array $data;

    public readonly float $at;

    /**
     * @param array<string, mixed> $data
     */
    public function __construct(public readonly string $name, array $data = [], ?float $at = null)
    {
        if (!in_array($name, self::NAMES, true)) {
            throw new \InvalidArgumentException('Unknown event name.');
        }
        $this->data = self::sanitize($data);
        $this->at   = $at ?? microtime(true);
    }

    /**
     * Keep logged values small and metadata-shaped as well as key-allow-listed. Event data may originate in
     * extensions or provider responses, so arbitrary nested values and free-form strings must never reach storage.
     *
     * @param array<string, mixed> $data
     * @return array<string, mixed>
     */
    private static function sanitize(array $data): array
    {
        $safe = [];
        foreach ($data as $key => $value) {
            if (!is_string($key) || !in_array($key, self::KEYS, true)) {
                continue;
            }

            if (in_array($key, self::INTEGER_KEYS, true)) {
                if (is_int($value) || (is_string($value) && preg_match('/^-?\\d+$/D', $value) === 1)) {
                    $safe[$key] = max(0, min(PHP_INT_MAX, (int) $value));
                }
                continue;
            }

            if ($key === 'tainted') {
                if (is_bool($value)) {
                    $safe[$key] = $value;
                }
                continue;
            }

            if (in_array($key, self::LIST_KEYS, true)) {
                if (!is_array($value)) {
                    continue;
                }
                $items = [];
                foreach (array_slice($value, 0, self::MAX_LIST_ITEMS) as $item) {
                    $normalized = self::safeCode($item);
                    if ($normalized !== null) {
                        $items[] = $normalized;
                    }
                }
                $safe[$key] = $items;
                continue;
            }

            $normalized = self::safeCode($value);
            if ($normalized !== null) {
                $safe[$key] = $normalized;
            }
        }

        return $safe;
    }

    private static function safeCode(mixed $value): ?string
    {
        if (!is_string($value) || $value === '' || strlen($value) > self::MAX_STRING_BYTES) {
            return null;
        }

        return preg_match('/^[A-Za-z0-9][A-Za-z0-9_.:\\/+-]*$/D', $value) === 1 ? $value : null;
    }

    /**
     * @since 0.1.0
     * @return array{v: int, name: string, at: float, data: array<string, mixed>}
     */
    public function toArray(): array
    {
        return ['v' => self::VERSION, 'name' => $this->name, 'at' => $this->at, 'data' => $this->data];
    }
}