feat(kpihistory): classify KPI metrics gauge-vs-rate for hourly rollups (plan #22 T2)

Add KpiRollupAggregation { Gauge, Rate } enum + KpiMetricAggregationCatalog.Resolve(source, metric)
that the hourly rollup fold (T3) consults. Rate = sum-per-hour for per-interval delta counters;
Gauge = last-value-per-hour default (also the safe fallback for unknown/new metrics, never throws).
totalEventsLastHour/errorEventsLastHour classified Gauge (rolling trailing-hour counts, not
per-interval deltas) per authoritative source semantics.

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj

src/ZB.MOM.WW.ScadaBridge.Commons/Types/Kpi/KpiMetricAggregation.cs

@@ -0,0 +1,125 @@
+namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi;
+
+/// <summary>
+/// How a KPI metric must be folded when an hour of one-minute
+/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Entities.Kpi.KpiSample"/> rows is
+/// aggregated into a single <c>KpiRollupHourly</c> row ("KPI History &amp; Trends"
+/// hourly rollups, deferred #22). The correct fold differs by metric semantics, and
+/// choosing the wrong one silently corrupts long-range trend charts.
+/// </summary>
+public enum KpiRollupAggregation
+{
+    /// <summary>
+    /// An instantaneous gauge (e.g. queue depth, buffered count, oldest-pending age).
+    /// The faithful hourly fold is <strong>last-value-per-hour</strong> — a gauge has
+    /// no meaningful sum across the 60 one-minute samples in an hour; summing would
+    /// invent a nonsensical total, whereas the latest reading is the value that a live
+    /// tile would have shown at the hour boundary.
+    /// </summary>
+    Gauge = 0,
+
+    /// <summary>
+    /// An already-windowed rate / delta counter (e.g. delivered-last-interval,
+    /// per-interval error counts). The faithful hourly fold is
+    /// <strong>sum-per-hour</strong> — each minute's sample is a fresh count of what
+    /// happened in that interval, so the hour's true total is the sum of its samples.
+    /// Folding a rate as last-value would keep one minute's delta and discard the other
+    /// 59, silently under-counting every long-range total.
+    /// </summary>
+    Rate = 1,
+}
+
+/// <summary>
+/// Authoritative classification of every KPI metric emitted by the four
+/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Kpi.IKpiSampleSource"/>
+/// implementations as a <see cref="KpiRollupAggregation.Gauge"/> or a
+/// <see cref="KpiRollupAggregation.Rate"/>, keyed by the <c>(source, metric)</c>
+/// pair. The hourly rollup fold consults this to pick last-value-per-hour vs.
+/// sum-per-hour for each series.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Keying by <c>(source, metric)</c> — not metric alone — is deliberate:
+/// <c>deliveredLastInterval</c> is emitted by both
+/// <see cref="KpiSources.NotificationOutbox"/> and <see cref="KpiSources.SiteCallAudit"/>,
+/// so a metric name is not globally unique. Every metric string is taken from the
+/// emitting source verbatim (shared <see cref="KpiMetrics"/> constants where they exist,
+/// otherwise the source's own private literal), so this catalog stays a faithful mirror
+/// of what actually lands in <c>KpiSample.Metric</c>.
+/// </para>
+/// <para>
+/// The catalog stores only the <see cref="KpiRollupAggregation.Rate"/> pairs; anything
+/// not listed — including an unknown, newly-added metric — resolves to
+/// <see cref="KpiRollupAggregation.Gauge"/>. Gauge is the safe default: last-value-per-hour
+/// never fabricates a total, so a metric that slips in without being classified degrades
+/// to a plausible reading rather than crashing the fold or silently multiplying a count.
+/// </para>
+/// </remarks>
+public static class KpiMetricAggregationCatalog
+{
+    // Metric literals for the sources that keep their names private (no shared
+    // KpiMetrics constant exists for these). Charted metrics use the KpiMetrics catalog.
+    private const string SiteCallAuditDeliveredLastInterval = "deliveredLastInterval";
+    private const string SiteHealthAlarmEvalErrors = "alarmEvalErrors";
+    private const string SiteHealthEventLogWriteFailures = "eventLogWriteFailures";
+
+    /// <summary>
+    /// The <c>(source, metric)</c> pairs classified as <see cref="KpiRollupAggregation.Rate"/>
+    /// (sum-per-hour). Every other emitted metric is a <see cref="KpiRollupAggregation.Gauge"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Rate members are per-interval / per-report deltas whose hour total is the sum of
+    /// its minute samples:
+    /// <list type="bullet">
+    ///   <item><c>NotificationOutbox/deliveredLastInterval</c> — rows delivered in the last KPI interval.</item>
+    ///   <item><c>SiteCallAudit/failedLastInterval</c> — cached calls that failed permanently in the last KPI interval.</item>
+    ///   <item><c>SiteCallAudit/deliveredLastInterval</c> — cached calls delivered in the last KPI interval.</item>
+    ///   <item><c>SiteHealth/scriptErrors</c>, <c>SiteHealth/alarmEvalErrors</c>,
+    ///     <c>SiteHealth/deadLetters</c>, <c>SiteHealth/eventLogWriteFailures</c> — raw error
+    ///     counts <em>per health-report interval</em> (site health reports carry raw counts per
+    ///     interval, not running totals), so they accumulate over the hour.</item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// <strong>Deliberately NOT Rate — the <c>*LastHour</c> audit metrics are Gauges.</strong>
+    /// <c>AuditLog/totalEventsLastHour</c> and <c>AuditLog/errorEventsLastHour</c> read as
+    /// "rate-like" by name, but <see cref="ZB.MOM.WW.ScadaBridge.AuditLog"/>'s sample source
+    /// computes each as a <em>rolling trailing-one-hour</em> count (a fixed 1-hour window,
+    /// re-evaluated at every capture). Each minute's value therefore already <em>is</em> the
+    /// last-hour total, and consecutive minutes overlap by 59 minutes. Summing the 60 samples
+    /// in an hour would count each event dozens of times (~60× over-count). The correct fold is
+    /// last-value-per-hour: at the hour boundary the latest rolling-hour count closely tracks
+    /// the hour's own volume, exactly like every other gauge. So both stay
+    /// <see cref="KpiRollupAggregation.Gauge"/>, overriding the tentative plan list per the
+    /// authoritative source semantics.
+    /// </para>
+    /// </remarks>
+    private static readonly HashSet<(string Source, string Metric)> RatePairs = new()
+    {
+        (KpiSources.NotificationOutbox, KpiMetrics.NotificationOutbox.DeliveredLastInterval),
+        (KpiSources.SiteCallAudit, KpiMetrics.SiteCallAudit.FailedLastInterval),
+        (KpiSources.SiteCallAudit, SiteCallAuditDeliveredLastInterval),
+        (KpiSources.SiteHealth, KpiMetrics.SiteHealth.ScriptErrors),
+        (KpiSources.SiteHealth, SiteHealthAlarmEvalErrors),
+        (KpiSources.SiteHealth, KpiMetrics.SiteHealth.DeadLetters),
+        (KpiSources.SiteHealth, SiteHealthEventLogWriteFailures),
+    };
+
+    /// <summary>
+    /// Resolves how the metric identified by <paramref name="source"/> +
+    /// <paramref name="metric"/> must be folded into an hourly rollup.
+    /// </summary>
+    /// <param name="source">The emitting KPI source (a <see cref="KpiSources"/> value).</param>
+    /// <param name="metric">The metric name as persisted in <c>KpiSample.Metric</c>.</param>
+    /// <returns>
+    /// <see cref="KpiRollupAggregation.Rate"/> for a known per-interval counter;
+    /// <see cref="KpiRollupAggregation.Gauge"/> for every known gauge <em>and</em> for any
+    /// unknown / newly-added <c>(source, metric)</c> pair. Never throws — the fold must not
+    /// crash on a metric added after this catalog was last updated.
+    /// </returns>
+    public static KpiRollupAggregation Resolve(string source, string metric) =>
+        RatePairs.Contains((source, metric))
+            ? KpiRollupAggregation.Rate
+            : KpiRollupAggregation.Gauge;
+}