namespace ZB.MOM.WW.Secrets.Abstractions;

/// <summary>
/// Provisions the schema backing an <see cref="ISecretStore"/>. Implementations are idempotent —
/// running a migration repeatedly is safe — and refuse to run against a store whose on-disk schema
/// version is <em>newer</em> than the build supports, rather than silently downgrading it.
/// </summary>
/// <remarks>
/// This seam exists so the startup migration hosted service and the CLI stay store-agnostic: the
/// SQLite store, the shared SQL-Server store, and any future provider are all provisioned through
/// the same call, and swapping the store never touches the migration wiring.
/// </remarks>
public interface ISecretsStoreMigrator
{
    /// <summary>Creates or updates the secret-store schema to the version this build supports.</summary>
    /// <param name="cancellationToken">A token to cancel the operation.</param>
    /// <returns>A task that completes when the schema is at the supported version.</returns>
    /// <exception cref="SecretStoreMigrationException">
    /// The store's schema version is newer than this build supports.
    /// </exception>
    Task MigrateAsync(CancellationToken cancellationToken);
}
