<?php

namespace App\Provisioning\Contracts;

use App\Models\ProvisioningRun;
use App\Provisioning\StepResult;

/**
 * One idempotent unit of a provisioning pipeline. Steps never call each other;
 * they depend only on the run's state and the service interfaces they need.
 */
interface ProvisioningStep
{
    /** Stable snake_case identifier used in events and idempotency checks. */
    public function key(): string;

    /** i18n key for the display label, e.g. hosts.step.<key>. */
    public function label(): string;

    /** Seconds this step may run before the runner treats it as timed out. */
    public function maxDuration(): int;

    public function execute(ProvisioningRun $run): StepResult;
}
