<?php
/**
 * Snapshot service contract.
 *
 * @package AbilityGuard
 */

declare( strict_types=1 );

namespace AbilityGuard\Contracts;

/**
 * Captures pre-invocation state as declared in the ability's safety config.
 */
interface SnapshotServiceInterface {

	/**
	 * Capture snapshot for a single invocation.
	 *
	 * @param string               $invocation_id UUID.
	 * @param array<string, mixed> $safety        The safety config from the ability.
	 * @param mixed                $input         Ability input.
	 *
	 * @return array{ pre_hash: string, snapshot_id: int|null, surfaces: array<string, mixed> }
	 */
	public function capture( string $invocation_id, array $safety, $input ): array;

	/**
	 * Capture post-invocation state and persist it on an existing snapshot row.
	 *
	 * @param int                  $snapshot_id Row id returned by capture().
	 * @param array<string, mixed> $safety      Safety config (same value passed to capture()).
	 * @param mixed                $input       Ability input.
	 */
	public function capture_post( int $snapshot_id, array $safety, $input ): void;
}