<?php

declare(strict_types=1);

namespace BotGuard\Services\Detection\Contracts;

use BotGuard\Services\Detection\ModuleResult;
use BotGuard\Services\Detection\SignalBag;

/**
 * Contract every detection module implements.
 *
 * Modules are pure analysers: given the normalized SignalBag they return a
 * ModuleResult and MUST NOT mutate global state. This keeps them independently
 * unit-testable with fixture signals (no DB, no HTTP).
 */
interface DetectionModuleInterface
{
    /**
     * Stable module key, matching the config/module_configs registry.
     */
    public function key(): string;

    /**
     * Analyse the signals and return a human-likelihood result.
     */
    public function analyze(SignalBag $signals): ModuleResult;
}
