namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Transport;

/// <summary>
/// Computes the CURRENT flattened-config revision hash of a deployed instance —
/// the same value the deployment pipeline produces and stores in
/// <c>DeployedConfigSnapshot.RevisionHash</c>. Transport's bundle importer uses
/// this to enumerate stale instances after a template overwrite: an
/// instance is stale when its freshly-computed hash no longer matches the hash
/// captured at deploy time.
/// <para>
/// The seam lives in Commons so the Transport component can depend on it without
/// referencing the DeploymentManager project (where the flattening pipeline that
/// implements it lives). The implementation re-flattens the instance via the
/// existing flattening pipeline over the SAME scoped <c>DbContext</c>, so it sees
/// any template rows the in-flight import has staged on the change tracker but
/// not yet committed.
/// </para>
/// </summary>
public interface IStaleInstanceProbe
{
    /// <summary>
    /// Computes the current flattened-config revision hash for the given instance,
    /// or <c>null</c> when the hash cannot be computed (e.g. the instance or its
    /// template chain cannot be resolved). Callers treat a <c>null</c> result as
    /// "cannot determine staleness" and skip the instance — staleness is
    /// informational, never a reason to abort an import.
    /// </summary>
    /// <param name="instanceId">The target instance's surrogate id.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The current revision hash (e.g. <c>sha256:...</c>), or <c>null</c>.</returns>
    Task<string?> GetCurrentRevisionHashAsync(int instanceId, CancellationToken cancellationToken = default);
}
