// <copyright file="IDecisionHook.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under the AGPL-3.0-or-later.
// </copyright>

using StellaOps.Findings.Ledger.Domain;

namespace StellaOps.Findings.Ledger.Services;

/// <summary>
/// Hook interface for decision recording events.
/// Implementations are called asynchronously after decision is persisted.
/// </summary>
/// <remarks>
/// Hooks are fire-and-forget; exceptions are logged but don't block the caller.
/// SPRINT_20260107_006_004_BE Task: OM-007
/// </remarks>
public interface IDecisionHook
{
    /// <summary>
    /// Called after a decision is recorded to the ledger.
    /// </summary>
    /// <param name="decision">The recorded decision event.</param>
    /// <param name="tenantId">The tenant identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task representing the asynchronous operation.</returns>
    Task OnDecisionRecordedAsync(
        DecisionEvent decision,
        string tenantId,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Context provided to decision hooks for enriched processing.
/// </summary>
public sealed record DecisionHookContext
{
    /// <summary>
    /// The decision event that was recorded.
    /// </summary>
    public required DecisionEvent Decision { get; init; }

    /// <summary>
    /// The tenant identifier.
    /// </summary>
    public required string TenantId { get; init; }

    /// <summary>
    /// When the decision was persisted to the ledger.
    /// </summary>
    public required DateTimeOffset PersistedAt { get; init; }

    /// <summary>
    /// The ledger event sequence number, if available.
    /// </summary>
    public long? SequenceNumber { get; init; }
}