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

/// <summary>
/// Process-wide monotonic version watermark over the template/instance
/// configuration graph.
///
/// <para>
/// Every mutation that lands through the configuration database bumps the
/// version of the affected template (or instance), plus a global counter and —
/// for edge-shaped changes (template added/removed, parent or composition edge
/// changed) — a separate <see cref="StructureVersion"/>. Consumers use the
/// watermark two ways:
/// </para>
/// <list type="bullet">
///   <item>
///     as the discriminator in a flatten-session cache key
///     (<c>templateId + version</c>), so a memoised template chain can never be
///     served after that template changed; and
///   </item>
///   <item>
///     as a staleness fast path — when neither the instance nor any template in
///     its chain has moved since a previously computed revision hash, the hash
///     is still current and a full re-flatten can be skipped.
///   </item>
/// </list>
///
/// <para>
/// Versions are in-memory and process-local. They are deliberately NOT
/// persisted: a restart (or the standby central node) simply starts from zero,
/// which invalidates every cached entry and falls back to the authoritative
/// full flatten. The watermark is therefore only ever able to cause EXTRA work,
/// never stale work — a correctness property that matters because the value is
/// not replicated between the two central nodes.
/// </para>
/// </summary>
public interface ITemplateGraphWatermark
{
    /// <summary>
    /// Monotonic counter bumped on every template- or instance-graph mutation.
    /// Useful as a coarse "did anything change at all" gate.
    /// </summary>
    long Global { get; }

    /// <summary>
    /// Monotonic counter bumped only when the SHAPE of the graph changes — a
    /// template row added or removed, a parent-template edge changed, or a
    /// composition row added/removed/repointed. A cached template-chain
    /// MEMBERSHIP is valid only while this value is unchanged; the per-template
    /// versions then cover the contents of each member.
    /// </summary>
    long StructureVersion { get; }

    /// <summary>Current version of a single template. Zero when never mutated in this process.</summary>
    /// <param name="templateId">Template id to read.</param>
    /// <returns>The template's monotonic version.</returns>
    long GetTemplateVersion(int templateId);

    /// <summary>Current version of a single instance (its override/binding rows). Zero when never mutated in this process.</summary>
    /// <param name="instanceId">Instance id to read.</param>
    /// <returns>The instance's monotonic version.</returns>
    long GetInstanceVersion(int instanceId);

    /// <summary>Records a mutation of the given template.</summary>
    /// <param name="templateId">Template whose version is bumped.</param>
    /// <param name="structural">
    /// When <c>true</c> the change altered the graph shape (add/remove/parent or
    /// composition edge) and <see cref="StructureVersion"/> is bumped too.
    /// </param>
    void BumpTemplate(int templateId, bool structural = false);

    /// <summary>Records a mutation of the given instance.</summary>
    /// <param name="instanceId">Instance whose version is bumped.</param>
    void BumpInstance(int instanceId);

    /// <summary>
    /// Records a mutation whose affected template/instance could not be
    /// attributed to a specific id. Bumps <see cref="Global"/> and
    /// <see cref="StructureVersion"/>, invalidating every chain-membership and
    /// staleness fast path — the safe, conservative fallback.
    /// </summary>
    void BumpAll();
}
