git.stella-ops.org/src/Policy/StellaOps.Policy.Registry/Services/IPromotionService.cs

using StellaOps.Policy.Registry.Contracts;

namespace StellaOps.Policy.Registry.Services;

/// <summary>
/// Service for managing policy pack promotions across environments.
/// Implements REGISTRY-API-27-008: Promotion bindings per tenant/environment.
/// </summary>
public interface IPromotionService
{
    /// <summary>
    /// Creates a promotion binding for a policy pack to an environment.
    /// </summary>
    Task<PromotionBinding> CreateBindingAsync(
        Guid tenantId,
        CreatePromotionBindingRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Promotes a policy pack to a target environment.
    /// </summary>
    Task<PromotionResult> PromoteAsync(
        Guid tenantId,
        Guid packId,
        PromoteRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the current binding for a pack/environment combination.
    /// </summary>
    Task<PromotionBinding?> GetBindingAsync(
        Guid tenantId,
        Guid packId,
        string environment,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Lists all bindings for a tenant.
    /// </summary>
    Task<PromotionBindingList> ListBindingsAsync(
        Guid tenantId,
        string? environment = null,
        Guid? packId = null,
        int pageSize = 20,
        string? pageToken = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the active policy pack for an environment.
    /// </summary>
    Task<ActiveEnvironmentPolicy?> GetActiveForEnvironmentAsync(
        Guid tenantId,
        string environment,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Rolls back to a previous promotion for an environment.
    /// </summary>
    Task<RollbackResult> RollbackAsync(
        Guid tenantId,
        string environment,
        RollbackRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the promotion history for an environment.
    /// </summary>
    Task<IReadOnlyList<PromotionHistoryEntry>> GetHistoryAsync(
        Guid tenantId,
        string environment,
        int limit = 50,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Validates a promotion is allowed before executing.
    /// </summary>
    Task<PromotionValidationResult> ValidatePromotionAsync(
        Guid tenantId,
        Guid packId,
        string targetEnvironment,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Request to create a promotion binding.
/// </summary>
public sealed record CreatePromotionBindingRequest
{
    public required Guid PackId { get; init; }
    public required string Environment { get; init; }
    public PromotionBindingMode Mode { get; init; } = PromotionBindingMode.Manual;
    public PromotionBindingRules? Rules { get; init; }
    public IReadOnlyDictionary<string, string>? Metadata { get; init; }
    public string? CreatedBy { get; init; }
}

/// <summary>
/// Request to promote a policy pack.
/// </summary>
public sealed record PromoteRequest
{
    public required string TargetEnvironment { get; init; }
    public string? ApprovalId { get; init; }
    public string? PromotedBy { get; init; }
    public string? Comment { get; init; }
    public bool Force { get; init; }
}

/// <summary>
/// Request to rollback a promotion.
/// </summary>
public sealed record RollbackRequest
{
    public string? TargetBindingId { get; init; }
    public int? StepsBack { get; init; }
    public string? RolledBackBy { get; init; }
    public string? Reason { get; init; }
}

/// <summary>
/// Promotion binding mode.
/// </summary>
public enum PromotionBindingMode
{
    Manual,
    AutomaticOnApproval,
    Scheduled,
    Canary
}

/// <summary>
/// Rules for automatic promotion.
/// </summary>
public sealed record PromotionBindingRules
{
    public IReadOnlyList<string>? RequiredApprovers { get; init; }
    public int? MinimumApprovals { get; init; }
    public bool RequireSuccessfulSimulation { get; init; }
    public int? MinimumSimulationInputs { get; init; }
    public TimeSpan? MinimumSoakPeriod { get; init; }
    public IReadOnlyList<string>? AllowedSourceEnvironments { get; init; }
}

/// <summary>
/// Promotion binding.
/// </summary>
public sealed record PromotionBinding
{
    public required string BindingId { get; init; }
    public required Guid TenantId { get; init; }
    public required Guid PackId { get; init; }
    public required string PackVersion { get; init; }
    public required string Environment { get; init; }
    public required PromotionBindingMode Mode { get; init; }
    public required PromotionBindingStatus Status { get; init; }
    public PromotionBindingRules? Rules { get; init; }
    public required DateTimeOffset CreatedAt { get; init; }
    public DateTimeOffset? ActivatedAt { get; init; }
    public DateTimeOffset? DeactivatedAt { get; init; }
    public string? CreatedBy { get; init; }
    public string? ActivatedBy { get; init; }
    public IReadOnlyDictionary<string, string>? Metadata { get; init; }
}

/// <summary>
/// Promotion binding status.
/// </summary>
public enum PromotionBindingStatus
{
    Pending,
    Active,
    Superseded,
    RolledBack,
    Disabled
}

/// <summary>
/// Result of a promotion operation.
/// </summary>
public sealed record PromotionResult
{
    public required bool Success { get; init; }
    public PromotionBinding? Binding { get; init; }
    public string? PreviousBindingId { get; init; }
    public string? Error { get; init; }
    public IReadOnlyList<string>? Warnings { get; init; }
}

/// <summary>
/// List of promotion bindings.
/// </summary>
public sealed record PromotionBindingList
{
    public required IReadOnlyList<PromotionBinding> Items { get; init; }
    public string? NextPageToken { get; init; }
    public int TotalCount { get; init; }
}

/// <summary>
/// Active policy pack for an environment.
/// </summary>
public sealed record ActiveEnvironmentPolicy
{
    public required string Environment { get; init; }
    public required Guid PackId { get; init; }
    public required string PackVersion { get; init; }
    public required string PackDigest { get; init; }
    public required string BindingId { get; init; }
    public required DateTimeOffset ActivatedAt { get; init; }
    public string? ActivatedBy { get; init; }
}

/// <summary>
/// Result of a rollback operation.
/// </summary>
public sealed record RollbackResult
{
    public required bool Success { get; init; }
    public PromotionBinding? RestoredBinding { get; init; }
    public string? RolledBackBindingId { get; init; }
    public string? Error { get; init; }
}

/// <summary>
/// Promotion history entry.
/// </summary>
public sealed record PromotionHistoryEntry
{
    public required string BindingId { get; init; }
    public required Guid PackId { get; init; }
    public required string PackVersion { get; init; }
    public required PromotionHistoryAction Action { get; init; }
    public required DateTimeOffset Timestamp { get; init; }
    public string? PerformedBy { get; init; }
    public string? Comment { get; init; }
    public string? PreviousBindingId { get; init; }
}

/// <summary>
/// Promotion history action types.
/// </summary>
public enum PromotionHistoryAction
{
    Promoted,
    RolledBack,
    Disabled,
    Superseded
}

/// <summary>
/// Result of promotion validation.
/// </summary>
public sealed record PromotionValidationResult
{
    public required bool IsValid { get; init; }
    public IReadOnlyList<PromotionValidationError>? Errors { get; init; }
    public IReadOnlyList<PromotionValidationWarning>? Warnings { get; init; }
}

/// <summary>
/// Promotion validation error.
/// </summary>
public sealed record PromotionValidationError
{
    public required string Code { get; init; }
    public required string Message { get; init; }
}

/// <summary>
/// Promotion validation warning.
/// </summary>
public sealed record PromotionValidationWarning
{
    public required string Code { get; init; }
    public required string Message { get; init; }
}