<?php

declare(strict_types=1);

namespace App\Framework\EventSourcing\Sagas;

use App\Framework\EventSourcing\DomainEvent;

/**
 * Saga Interface
 *
 * Long-running business processes that coordinate across multiple aggregates
 * Also known as Process Managers in DDD terminology
 */
interface SagaInterface
{
    /**
     * Get unique saga identifier
     */
    public function getSagaId(): SagaId;

    /**
     * Get saga name for identification
     */
    public function getName(): string;

    /**
     * Handle incoming event
     * Returns commands to be executed as result of event
     *
     * @return array<object> Commands to execute
     */
    public function handle(DomainEvent $event): array;

    /**
     * Get events this saga is interested in
     *
     * @return array<class-string> Event class names
     */
    public function subscribedTo(): array;

    /**
     * Get current saga state
     */
    public function getState(): SagaState;

    /**
     * Check if saga is completed
     */
    public function isCompleted(): bool;

    /**
     * Compensate (rollback) saga on failure
     * Returns compensation commands
     *
     * @return array<object> Compensation commands
     */
    public function compensate(string $reason): array;
}
