// <copyright file="IAiAttestationService.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under the BUSL-1.1.
// </copyright>

using StellaOps.AdvisoryAI.Attestation.Models;

namespace StellaOps.AdvisoryAI.Attestation;

/// <summary>
/// Service for creating and verifying AI attestations.
/// Sprint: SPRINT_20260109_011_001 Task: AIAT-002
/// </summary>
public interface IAiAttestationService
{
    /// <summary>
    /// Creates an attestation for an AI run.
    /// </summary>
    /// <param name="attestation">The attestation to create.</param>
    /// <param name="sign">Whether to sign the attestation.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The created attestation with optional signature.</returns>
    Task<AiAttestationResult> CreateRunAttestationAsync(
        AiRunAttestation attestation,
        bool sign = true,
        CancellationToken ct = default);

    /// <summary>
    /// Creates an attestation for a specific claim.
    /// </summary>
    /// <param name="attestation">The claim attestation to create.</param>
    /// <param name="sign">Whether to sign the attestation.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The created attestation with optional signature.</returns>
    Task<AiAttestationResult> CreateClaimAttestationAsync(
        AiClaimAttestation attestation,
        bool sign = true,
        CancellationToken ct = default);

    /// <summary>
    /// Verifies an AI run attestation.
    /// </summary>
    /// <param name="runId">The run ID to verify.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Verification result.</returns>
    Task<AiAttestationVerificationResult> VerifyRunAttestationAsync(
        string runId,
        CancellationToken ct = default);

    /// <summary>
    /// Verifies a claim attestation.
    /// </summary>
    /// <param name="claimId">The claim ID to verify.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Verification result.</returns>
    Task<AiAttestationVerificationResult> VerifyClaimAttestationAsync(
        string claimId,
        CancellationToken ct = default);

    /// <summary>
    /// Gets a run attestation by ID.
    /// </summary>
    /// <param name="runId">The run ID.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The attestation if found.</returns>
    Task<AiRunAttestation?> GetRunAttestationAsync(
        string runId,
        CancellationToken ct = default);

    /// <summary>
    /// Gets claim attestations for a run.
    /// </summary>
    /// <param name="runId">The run ID.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>All claim attestations for the run.</returns>
    Task<IReadOnlyList<AiClaimAttestation>> GetClaimAttestationsAsync(
        string runId,
        CancellationToken ct = default);

    /// <summary>
    /// Lists recent run attestations.
    /// </summary>
    /// <param name="tenantId">Tenant filter.</param>
    /// <param name="limit">Maximum results.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Recent attestations.</returns>
    Task<IReadOnlyList<AiRunAttestation>> ListRecentAttestationsAsync(
        string tenantId,
        int limit = 100,
        CancellationToken ct = default);
}